feat: Implement core services for validation, vector querying, storage, and tier management

- Introduced `ValidationService` to handle environment variable validation, JWT token checks, and access tag validation.
- Created `VectorQueryService` for querying vector stores with security filters, including role-based access control and classification checks.
- Developed `VectorStorageService` to manage vector storage with batching, metadata handling, and usage tracking.
- Added `WorkflowDecorators` for logging and error handling in workflow steps.
- Implemented `TierManagementService` to manage subscription tiers, validate access based on quotas, and track usage statistics.
- Enhanced logging capabilities across services for better traceability and debugging.
- Established interfaces for query inputs, results, and storage metadata to ensure type safety and clarity.

Author: ssdeanx

src/cli/index.ts

@@ -6,7 +6,7 @@ import {
     logProgress,
     log,
 } from '../mastra/config/logger'
-import { tierManagementService } from '../mastra/config/tier-management-service'
+import { tierManagementService } from '../mastra/services/tier-management-service'
 import type { SubscriptionTier } from '../mastra/config/role-hierarchy'
 import * as dotenv from 'dotenv'
 import * as fs from 'fs/promises'

src/mastra/agents/index.ts

@@ -1,7 +1,6 @@
 export type { EditorRuntimeContext } from "./editorAgent";
 export type { ResearchRuntimeContext } from "./researchAgent";
 export type { WeatherRuntimeContext } from "./weather-agent";
-export type { SqlAgentRuntimeContext } from "./sql";
 export type { ReportRuntimeContext } from "./reportAgent";
 export type { ImageRuntimeContext } from "./image";
 export type { StockRuntimeContext } from "./stockAnalysisAgent";
@@ -47,7 +46,6 @@ export { reportAgent } from "./reportAgent";
 export { researchAgent } from "./researchAgent";
 export { researchPaperAgent } from "./researchPaperAgent";
 export { scriptWriterAgent } from "./scriptWriterAgent";
-export { sqlAgent } from "./sql";
 export { stockAnalysisAgent } from "./stockAnalysisAgent";
 export { weatherAgent } from "./weather-agent";
 

src/mastra/config/role-hierarchy.ts

@@ -116,26 +116,60 @@ export function getInheritorRoles(targetRole: string): string[] {
  * Supabase-compatible tier configuration
  */
 export interface TierConfig {
-    maxRequests: number
+    // Backwards-compatible: maxRequests remains for legacy callers
+    maxRequests?: number
+    // Explicit quotas used throughout services
+    maxDocuments: number
+    maxApiRequestsPerDay: number
+    maxUsersPerTenant: number
     features: string[]
     rlsPolicy: string
+    supportLevel?: 'community' | 'email' | 'priority' | 'phone_24x7'
+    customIntegrations?: boolean
+    advancedAnalytics?: boolean
+    whiteLabel?: boolean
+    onPremise?: boolean
 }
 
 export const TIER_CONFIGS: Record<SubscriptionTier, TierConfig> = {
     free: {
         maxRequests: 100,
+        maxDocuments: 250,
+        maxApiRequestsPerDay: 100,
+        maxUsersPerTenant: 1,
         features: ['basic-chat', 'public-docs'],
         rlsPolicy: RLS_POLICIES.publicRead,
+        supportLevel: 'community',
+        customIntegrations: false,
+        advancedAnalytics: false,
+        whiteLabel: false,
+        onPremise: false,
     },
     pro: {
         maxRequests: 10000,
+        maxDocuments: 10000,
+        maxApiRequestsPerDay: 10000,
+        maxUsersPerTenant: 100,
         features: ['advanced-chat', 'private-docs', 'api-access'],
         rlsPolicy: RLS_POLICIES.proFeatures,
+        supportLevel: 'email',
+        customIntegrations: true,
+        advancedAnalytics: true,
+        whiteLabel: false,
+        onPremise: false,
     },
     enterprise: {
         maxRequests: -1, // unlimited
+        maxDocuments: -1,
+        maxApiRequestsPerDay: -1,
+        maxUsersPerTenant: -1,
         features: ['unlimited-chat', 'all-docs', 'custom-models', 'admin-panel'],
         rlsPolicy: RLS_POLICIES.enterpriseFeatures,
+        supportLevel: 'priority',
+        customIntegrations: true,
+        advancedAnalytics: true,
+        whiteLabel: true,
+        onPremise: true,
     },
 }
 
@@ -146,13 +180,40 @@ export function getTierConfig(tier: SubscriptionTier): TierConfig {
     return TIER_CONFIGS[tier]
 }
 
+/**
+ * Backwards-compatible tier quota accessor used by services
+ */
+export function getTierQuota(tier: SubscriptionTier): {
+    maxDocuments: number
+    maxApiRequestsPerDay: number
+    maxUsersPerTenant: number
+    features: string[]
+    rlsPolicy: string
+} {
+    const cfg = getTierConfig(tier)
+    return {
+        maxDocuments: cfg.maxDocuments,
+        maxApiRequestsPerDay: cfg.maxApiRequestsPerDay,
+        maxUsersPerTenant: cfg.maxUsersPerTenant,
+        features: cfg.features,
+        rlsPolicy: cfg.rlsPolicy,
+    }
+}
+
 /**
  * Check if a feature is available in a tier
  */
 export function hasFeature(tier: SubscriptionTier, feature: string): boolean {
     return TIER_CONFIGS[tier].features.includes(feature)
 }
 
+/**
+ * Backwards-compatible feature check
+ */
+export function isTierFeatureEnabled(tier: SubscriptionTier, feature: string) {
+    return hasFeature(tier, feature)
+}
+
 /**
  * Get the minimum tier required for a role
  */
@@ -169,6 +230,24 @@ export function getTierForRole(role: string): SubscriptionTier {
     return 'free'
 }
 
+/**
+ * Minimum tier required for a given classification level
+ */
+export function getMinimumTierForClassification(
+    classification: 'public' | 'internal' | 'confidential'
+): SubscriptionTier {
+    switch (classification) {
+        case 'public':
+            return 'free'
+        case 'internal':
+            return 'pro'
+        case 'confidential':
+            return 'enterprise'
+        default:
+            return 'free'
+    }
+}
+
 /**
  * Supabase RLS Policy Generator
  * Returns the appropriate policy for a given role

src/mastra/experiments/agent-experiments.ts

@@ -1,6 +1,5 @@
 import { createScorer, runEvals } from '@mastra/core/evals';
 import { contentStrategistAgent } from '../agents/contentStrategistAgent'
-import { sqlAgent } from '../agents/sql'
 import { copywriterAgent } from '../agents/copywriterAgent'
 import { scriptWriterAgent } from '../agents/scriptWriterAgent'
 import { stockAnalysisAgent } from '../agents/stockAnalysisAgent'
@@ -45,27 +44,6 @@ export async function runContentStrategistExperiment() {
     return results
 }
 
-export async function runSqlAgentExperiment() {
-    console.log('Running SQL Agent Experiment...')
-    const results = await runEvals({
-        target: sqlAgent,
-        data: [
-            {
-                input: 'What are the top 5 most populous cities in Europe?',
-            },
-            {
-                input: 'List all cities in France with a population over 1 million.',
-            },
-            {
-                input: 'Show me the average population of cities in Asia.',
-            }
-        ],
-        scorers: [sqlValidityScorer, responseQualityScorer]
-    })
-    console.log('SQL Agent Experiment Results:', JSON.stringify(results, null, 2))
-    return results
-}
-
 export async function runCopywriterExperiment() {
     console.log('Running Copywriter Experiment...')
     const results = await runEvals({
@@ -221,7 +199,6 @@ export async function runWeatherAgentExperiment() {
 
 export async function runAllExperiments(p0: unknown) {
     await runContentStrategistExperiment()
-    await runSqlAgentExperiment()
     await runCopywriterExperiment()
     await runScriptWriterExperiment()
     await runStockAnalysisExperiment()

src/mastra/services/AGENTS.md

@@ -0,0 +1,37 @@
+<!-- AGENTS-META {"title":"Mastra Services","version":"1.2.0","last_updated":"2025-10-15T17:01:00Z","applies_to":"/src/mastra/services","tags":["layer:backend","domain:rag","type:services","status":"stable"],"status":"stable"} -->
+
+# Services Directory (`/src/mastra/services`)
+
+## Persona
+
+**Name:** Senior Backend Engineer  
+**Role Objective:** Encapsulate stateless, reusable domain and infrastructure logic consumed by tools and workflow steps.
+
+## Purpose
+
+Provide single-responsibility functional units (auth, role expansion, vector retrieval, document processing, embedding, storage, validation) enabling higher-level orchestration layers to remain thin and declarative.
+
+## Key Files
+
+| File                          | Responsibility                         | Notes                                 |
+| ----------------------------- | -------------------------------------- | ------------------------------------- |
+| `AuthenticationService.ts`    | JWT verification & policy seed         | Coordinate with jwt-auth.tool         |
+| `RoleService.ts`              | Role expansion & hierarchy logic       | Aligns with `role-hierarchy.ts`       |
+| `VectorQueryService.ts`       | Secure filtered vector search assembly | Applies classification & role filters |
+| `DocumentProcessorService.ts` | High-level indexing orchestration      | Calls chunk, embed, store services    |
+| `DocumentIndexingService.ts`  | Document indexing coordination         | Orchestrates the indexing pipeline    |
+| `ChunkingService.ts`          | Strategy-based text segmentation       | Tune chunk sizes & overlap            |
+| `EmbeddingService.ts`         | Embedding generation & batching        | Retry & backoff logic                 |
+| `VectorStorageService.ts`     | Persistence into PostgreSQL with PgVector                | Attaches security tags                |
+| `RateLimitingService.ts`      | Request rate limiting & throttling     | Prevents abuse and ensures fair usage |
+| `TierManagementService.ts`    | User tier management & upgrades        | Handles subscription and feature access|
+| `ValidationService.ts`        | Common validation helpers              | Env & structural guards               |
+| `WorkflowDecorators.ts`       | Step wrapper utilities                 | Logging, timing, error wrapping       |
+
+## Change Log
+
+| Version | Date (UTC) | Change                                                  |
+| ------- | ---------- | ------------------------------------------------------- |
+| 1.2.0   | 2025-10-15 | Added missing DocumentIndexingService.ts, RateLimitingService.ts, and TierManagementService.ts to documentation |
+| 1.1.0   | 2025-10-08 | Verified content accuracy and updated metadata.         |
+| 1.0.0   | 2025-09-24 | Standardized template applied; legacy content preserved |

…c/mastra/config/AuthenticationService.ts …mastra/services/AuthenticationService.tssrc/mastra/config/AuthenticationService.ts renamed to src/mastra/services/AuthenticationService.ts src/mastra/config/AuthenticationService.ts renamed to src/mastra/services/AuthenticationService.ts

@@ -1,7 +1,7 @@
 import { jwtVerify } from 'jose'
 
 import { ValidationService } from './ValidationService'
-import { RoleService } from './role-service'
+import { RoleService } from './RoleService'
 import { log } from '../config/logger'
 
 export interface JWTClaims {