interface FeatureDefinition {
  name: string;
  category: 'stationary' | 'behavioral' | 'transactional';
  maxStalenessSeconds: number;
  aggregationWindow?: string;
}

const featureRegistry: Record<string, FeatureDefinition> = {
  user_tenure_days: { name: 'user_tenure_days', category: 'stationary', maxStalenessSeconds: 86400 },
  session_page_views: { name: 'session_page_views', category: 'behavioral', maxStalenessSeconds: 30 },
  last_5m_transaction_count: { name: 'last_5m_transaction_count', category: 'transactional', maxStalenessSeconds: 10 }
};

class FeatureRouter {
  private batchQueue: FeatureDefinition[] = [];
  private streamQueue: FeatureDefinition[] = [];

  classifyAndRoute(features: FeatureDefinition[]): void {
    features.forEach(f => {
      if (f.maxStalenessSeconds <= 60) {
        this.streamQueue.push(f);
      } else {
        this.batchQueue.push(f);
      }
    });
  }

  getExecutionPlan(): { batch: FeatureDefinition[]; stream: FeatureDefinition[] } {
    return { batch: this.batchQueue, stream: this.streamQueue };
  }
}

interface TrainingEvent {
  eventId: string;
  userId: string;
  eventTimestamp: Date;
  label: number;
}

interface FeatureSnapshot {
  featureName: string;
  userId: string;
  value: number;
  computedAt: Date;
}

class PointInTimeResolver {
  resolve(
    events: TrainingEvent[],
    featureHi

story: FeatureSnapshot[] ): Array<TrainingEvent & Record<string, number>> { return events.map(event => { const relevantFeatures = featureHistory .filter(f => f.userId === event.userId && f.computedAt <= event.eventTimestamp) .reduce((acc, curr) => { acc[curr.featureName] = curr.value; return acc; }, {} as Record<string, number>);

  return { ...event, ...relevantFeatures };
});

} }

### Step 4: Capture Serving Snapshots for Backfill
Streaming pipelines overwrite state. Without explicit logging, historical feature values are lost, making model retraining impossible. The audit logger writes a durable copy of every feature vector served to the model.

```typescript
class ServingAuditLogger {
  private offlineStore: Map<string, FeatureSnapshot[]> = new Map();

  logServingVector(userId: string, timestamp: Date, featureVector: Record<string, number>): void {
    const snapshots = Object.entries(featureVector).map(([name, value]) => ({
      featureName: name,
      userId,
      value,
      computedAt: timestamp
    }));

    const key = `${userId}_${timestamp.toISOString()}`;
    this.offlineStore.set(key, snapshots);
  }

  exportForBackfill(): FeatureSnapshot[] {
    return Array.from(this.offlineStore.values()).flat();
  }
}

Architecture Rationale

• Why separate paths? Batch engines excel at heavy aggregations over large datasets. Streaming engines excel at low-latency state updates. Forcing one engine to handle both creates either unacceptable latency or unmanageable compute costs.
• Why merge at serving? The online feature store acts as a temporal router. It pulls batch-computed aggregates for slow-moving features and streams the latest windowed values for fast-moving features. The model receives a single payload without needing to know the underlying compute topology.
• Why point-in-time joins? Training-serving skew is the primary cause of production model degradation. Enforcing temporal boundaries during dataset construction guarantees that offline evaluation reflects actual inference conditions.

Pitfall Guide

1. The Future Leakage Trap

Explanation: Joining feature tables without temporal constraints pulls values computed after the target event. The model learns patterns that are impossible to reproduce in production. Fix: Implement point-in-time joins that filter features by computedAt <= eventTimestamp. Validate with temporal cross-validation splits.

2. Streaming Everything

Explanation: Treating all features as real-time requirements inflates infrastructure costs and operational overhead. Static features like user demographics or product categories do not benefit from sub-second updates. Fix: Classify features by decay rate. Route stationary and slowly-changing features to batch pipelines. Reserve streaming for behavioral and transactional signals.

3. Ignoring Out-of-Order Events

Explanation: Network partitions and producer retries cause events to arrive late. Without watermarking, streaming aggregations produce incorrect windowed values or drop data silently. Fix: Configure event-time watermarks with allowed lateness thresholds. Use stateful processors that can handle late arrivals without breaking window boundaries.

4. The Backfill Blind Spot

Explanation: Streaming pipelines maintain in-memory or key-value state optimized for reads. They rarely persist historical snapshots. When retraining is required, teams discover they lack the exact feature values served during production inference. Fix: Implement a serving audit log that writes feature vectors to durable offline storage. Define features declaratively so historical data can be replayed through the same transformation logic.

5. Definitional Drift Across Teams

Explanation: Multiple teams compute identical features independently. Schema changes update one pipeline but not others. Features with the same name return divergent values, causing cross-model inconsistency. Fix: Centralize feature definitions in a declarative registry. Enforce a single source of truth for transformation logic. Use versioned feature contracts that break pipelines on schema mismatches.

6. Treating Freshness as a Model Hyperparameter

Explanation: Teams attempt to compensate for stale data by adjusting model complexity or regularization. This masks the root cause and creates fragile models that fail when data velocity changes. Fix: Treat feature latency as an infrastructure SLA. Monitor staleness metrics alongside model performance. Decouple model tuning from pipeline reliability.

7. Merging Logic in the Model Layer

Explanation: Pushing batch/stream merging logic into the inference service couples model code to pipeline topology. Updates to feature routing require model redeployments. Fix: Keep merging logic in the online feature store or a dedicated serving proxy. The model should receive a flat, pre-merged feature vector.

Production Bundle

Action Checklist

• Classify all features by decay rate and assign maxStalenessSeconds thresholds
• Route stationary features to scheduled batch jobs and behavioral features to streaming processors
• Implement point-in-time joins in the training dataset construction pipeline
• Deploy a serving audit logger to capture feature vectors for offline backfill
• Define feature transformations declaratively to enable historical replay
• Configure event-time watermarks and allowed lateness for all streaming windows
• Centralize feature definitions in a versioned registry to prevent drift
• Monitor feature staleness SLAs alongside model performance metrics

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Fraud detection with <60s SLA	Streaming speed layer + point-in-time training	Behavioral signals decay rapidly; batch intervals create blind spots	High compute, but prevents revenue loss from undetected fraud
Customer segmentation with daily refresh	Scheduled batch pipeline	Demographic and historical aggregates change slowly; streaming adds unnecessary overhead	Low compute, predictable scheduling, minimal operational burden
Multi-model platform with shared features	Centralized feature registry + hybrid routing	Prevents definitional drift and compute duplication across teams	Medium initial investment, long-term savings via reuse
Regulatory compliance requiring audit trails	Serving audit logger + declarative backfill	Enables exact reproduction of production feature states for model validation	Moderate storage cost, high compliance value

Configuration Template

feature_pipeline:
  routing:
    batch_threshold_seconds: 60
    merge_strategy: "online_store_fallback"
    
  features:
    - name: user_tenure_days
      category: stationary
      max_staleness: 86400
      compute: batch
      schedule: "0 2 * * *"
      
    - name: session_page_views
      category: behavioral
      max_staleness: 30
      compute: stream
      window: "5m"
      watermark: "10s"
      
    - name: last_5m_transaction_count
      category: transactional
      max_staleness: 10
      compute: stream
      window: "5m"
      watermark: "5s"
      
  training:
    point_in_time_join: true
    temporal_column: "event_timestamp"
    feature_timestamp_column: "computed_at"
    
  backfill:
    audit_logging: true
    offline_storage: "s3://ml-features/audit-logs"
    replay_enabled: true

Quick Start Guide

1. Inventory your features: Export your current feature list and annotate each with a maxStalenessSeconds value based on business requirements and signal decay characteristics.
2. Deploy the routing layer: Implement the classification logic to split features into batch and stream queues. Configure your batch scheduler and streaming processors accordingly.
3. Enforce temporal correctness: Update your training dataset construction pipeline to use point-in-time joins. Validate that no features computed after the target event timestamp leak into the training set.
4. Enable backfill logging: Activate the serving audit logger to capture feature vectors alongside inference requests. Route logs to durable offline storage for historical replay.
5. Validate end-to-end: Run a shadow inference job comparing batch-only, stream-only, and hybrid feature sets. Measure prediction variance and confirm that staleness SLAs are met under production load.