Flow PR #187088 Incident Root Cause Analysis - ReturnValuePruner Bug

incident_root_cause_analysis.md

🔴 CRITICAL BUG IDENTIFIED

The incident was caused by a logic error in the a_primitive? method that breaks handling of nil values.

The Problem

Old logic (working):

elsif usage_schema.is_a?(Maestro::Runtime::Usage::Primitive) && 
      [Hash, Array].exclude?(json_response.class) && 
      !json_response.nil?
  return json_response

New logic (broken):

def a_primitive?(json_response)
  json_response.present? && NON_PRIMITIVE_TYPES.exclude?(json_response.class)
end

The Critical Difference

1. Old code: Used !json_response.nil? - returns false only for nil
2. New code: Uses json_response.present? - returns false for nil, false, empty string "", empty array [], etc.

Impact

When a primitive field has a false boolean value:

• Old code: Would correctly identify false as a primitive and return it
• New code: false.present? returns false, so a_primitive?(false) returns false
• This causes the code to fall through to raise_value_type_mismatch
• Result: Raises ValueTypeMismatch exception when processing boolean false values

Example Failure Scenario

# Workflow returns: { "return_value" => { "is_enabled" => false } }
# With usage_schema expecting a boolean primitive

# New code flow:
1. traverse_usage_schema called with (Primitive::Boolean, false)
2. a_primitive?(false) returns false because false.present? is false
3. Falls through to raise_value_type_mismatch
4. Raises: "Value false is of type FalseClass but should be of type Maestro::Runtime::Usage::Primitive::Boolean"

Why This Caused an Incident

Any workflow that:

1. Returns a boolean false value
2. Or returns an empty string ""
3. Or any other "falsy" value that fails the present? check

Would immediately start failing with ValueTypeMismatch exceptions, breaking production workflows.

The Fix

Replace:

def a_primitive?(json_response)
  json_response.present? && NON_PRIMITIVE_TYPES.exclude?(json_response.class)
end

With:

def a_primitive?(json_response)
  !json_response.nil? && NON_PRIMITIVE_TYPES.exclude?(json_response.class)
end

Or even simpler:

def a_primitive?(json_response)
  NON_PRIMITIVE_TYPES.exclude?(json_response.class) && !json_response.nil?
end

This preserves the original logic that only excludes nil values, not all falsy values.