Skip to main content

sdac-validate-fringe

Purpose​

Validates fringe benefit amounts, salary-fringe relationships, and optional fringe statistics using a position-first model.

Tool type​

Deterministic (rule-based)

Tool ID​

sdac-validate-fringe

Inputs​

  • report_id (string)
  • record_ids (number[], optional)
  • include_statistical_analysis (boolean, optional, default: false)

Outputs​

  • success, passed
  • error_count, warning_count
  • errors, warnings, executed_rules
  • flagged_positions (optional) -- Position-level findings with linked occupants, aggregated salary/fringe, reasons, and confidence
  • limitations (optional) -- Reserved for non-blocking analysis notes
  • statistics (optional)

Example output​

{
  "success": true,
  "passed": false,
  "error_count": 1,
  "warning_count": 1,
  "errors": [
    {
      "rule_id": "FRINGE_WITH_ZERO_SALARY",
      "row_number": 48,
      "message": "Fringe is claimed for a position with $0 claimable salary.",
      "severity": "ERROR"
    }
  ],
  "warnings": [
    {
      "rule_id": "HIGH_FRINGE_RATE",
      "row_number": 52,
      "message": "Fringe rate is unusually high compared with salary.",
      "severity": "WARNING"
    }
  ],
  "executed_rules": [
    "FRINGE_WITH_ZERO_SALARY",
    "HIGH_FRINGE_RATE"
  ],
  "flagged_positions": [
    {
      "row_number": 48,
      "linked_rows": [
        48
      ],
      "aggregated_salary": 0,
      "aggregated_fringe": 4200,
      "reasons": [
        "Fringe claimed with no salary"
      ],
      "confidence": "HIGH"
    }
  ],
  "statistics": {
    "total_fringe": 312000,
    "median_fringe_rate": 24.8
  }
}

Functional details​

  • Aggregates salary and fringe at the canonical position level before evaluating fringe-rate reasonableness.
  • Flags fringe-only entries and missing salary linkage.
  • Detects duplicate fringe values for copy/paste risk.
  • Computes optional statistical outlier checks.
  • Applies role-family-aware fringe thresholds so paraprofessionals are not over-flagged by generic rate rules.
  • Carries ambiguity forward when replacement/support rows cannot be linked confidently to a main-roster position.

Implementation details​

  • High-fringe threshold: $20,000 claimable per quarter.
  • Validates fringe without salary (FRINGE_WITHOUT_SALARY).
  • Detects consecutive duplicate fringe values (FRINGE_DUPLICATE_CONSECUTIVE).
  • Optional stats compute mean/median/std dev and FRINGE_OUTLIER detection.
  • Uses aggregated claimable fringe + salary to compute position-level fringe-rate warnings.
  • Emits flagged_positions entries with position_id, position_label, main_row_number, linked_record_ids, occupants, reasons, and confidence.
  • Keeps the legacy claimable-based federal-funds fringe calculation path in place.
  • Statistics run on non-zero fringe values when enabled.

Code Location: packages/domain-sdac/src/tools/validate-fringe.tool.ts