fix: various edge cases in targeting

docs/reference/flag-definitions.md

@@ -190,6 +190,8 @@ Conditions can be used to control the logical flow and grouping of targeting rul
 
 Operations are used to take action on, or compare properties retrieved from the context.
 These are provided out-of-the-box by JsonLogic.
+It's worth noting that JsonLogic operators never throw exceptions or abnormally terminate due to invalid input.
+As long as a JsonLogic operator is structurally valid, it will return a falsy/nullish value.
 
 | Operator               | Description                                                          | Context type | Example                                                                                                                                                                |
 | ---------------------- | -------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -214,6 +216,7 @@ These are provided out-of-the-box by JsonLogic.
 
 These are custom operations specific to flagd and flagd providers.
 They are purpose built extensions to JsonLogic in order to support common feature flag use cases.
+Consistent with build-in JsonLogic operators, flagd's custom operators return falsy/nullish values with invalid inputs.
 
 | Function                           | Description                                         | Example                                                                                                                                                                                                                                                                                  |
 | ---------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

docs/reference/specifications/custom-operations/fractional-operation-spec.md

@@ -13,7 +13,7 @@ hash function should be used. This is to ensure that flag resolution requests yi
 regardless of which implementation of the in-process flagd provider is being used.
 
 The supplied array must contain at least two items, with the first item being an optional [json logic variable declaration](https://jsonlogic.com/operations.html#var)
-specifying the bucketing property to base the distribution of values on. If not supplied, a concatenation of the
+specifying the bucketing property to base the distribution of values on. If the bucketing property expression doesn't return a string, a concatenation of the
 `flagKey` and `targetingKey` are used: `{"cat": [{"var":"$flagd.flagKey"}, {"var":"targetingKey"}]}`.
 The remaining items are `arrays`, each with two values, with the first being `string` item representing the name of the variant, and the
 second being a `float` item representing the percentage for that variant. The percentages of all items must add up to
@@ -62,8 +62,8 @@ The following flow chart depicts the logic of this evaluator:
 ```mermaid
 flowchart TD
 A[Parse targetingRule] --> B{Is an array containing at least one item?};
-B -- Yes --> C{Is targetingRule at index 0 a string?};
-B -- No --> D[return nil]
+B -- Yes --> C{Does expression at index 0 return a string?};
+B -- No --> D[return null]
 C -- No --> E[bucketingPropertyValue := default to targetingKey];
 C -- Yes --> F[bucketingPropertyValue := targetingRule at index 0];
 E --> G[Iterate through the remaining elements of the targetingRule array and parse the variants and their percentages];

docs/reference/specifications/custom-operations/semver-operation-spec.md

@@ -21,7 +21,7 @@ The 'sem_ver' evaluation rule contains exactly three items:
 1. Target property value: the resolved value of the target property referenced in the targeting rule
 2. Operator: One of the following: `=`, `!=`, `>`, `<`, `>=`, `<=`, `~` (match minor version), `^` (match major version)
 3. Target value: this needs to resolve to a semantic versioning string. If this condition is not met, the evaluator should
-log an appropriate error message and return `nil`
+log an appropriate error message and return `false`
 
 The `sem_ver` evaluation returns a boolean, indicating whether the condition has been met.
 
@@ -35,7 +35,7 @@ The following flow chart depicts the logic of this evaluator:
 flowchart TD
 A[Parse targetingRule] --> B{Is an array containing exactly three items?};
 B -- Yes --> C{Is targetingRule at index 0 a semantic version string?};
-B -- No --> D[Return nil];
+B -- No --> D[Return false];
 C -- Yes --> E{Is targetingRule at index 1 a supported operator?};
 C -- No --> D;
 E -- Yes --> F{Is targetingRule at index 2 a semantic version string?};

docs/reference/specifications/custom-operations/string-comparison-operation-spec.md

@@ -32,7 +32,7 @@ The following flow chart depicts the logic of this evaluator:
 flowchart TD
 A[Parse targetingRule] --> B{Is an array containing exactly two items?};
 B -- Yes --> C{Is targetingRule at index 0 a string?};
-B -- No --> D[Return nil];
+B -- No --> D[Return false];
 C -- Yes --> E{Is targetingRule at index 1 a string?};
 C -- No --> D;
 E -- No --> D;