feat(flags): report unresolved local flags on EvaluateFlags snapshots

.changeset/unresolved-local-flags.md

@@ -0,0 +1,12 @@
+---
+"posthog-go": minor
+---
+
+Report flags that local evaluation could not resolve on `EvaluateFlags` snapshots. `FeatureFlagEvaluations.UnresolvedFlags()` maps each such flag to an `UnresolvedFlagReason` (`experience_continuity`, `unsupported_definition`, `unresolved_dependency` or `missing_context`), and `InconclusiveMatchError` and `RequiresServerEvaluationError` carry the reason in a new `Reason` field. When definitions load, log one warning per flag that local evaluation can never resolve (experience continuity, a static cohort, an unknown operator, a malformed value, or a missing or circular flag dependency), and again only when its definition changes.
+
+Behavior changes:
+
+- A condition with a filter that local evaluation can't check and a filter that does not match now resolves locally as no match. Before, such a flag fell back to a remote request, or stayed unresolved with `OnlyEvaluateLocally`.
+- An inactive flag with experience continuity enabled now resolves to `false` locally instead of falling back to a remote request.
+- `$feature_flag_called` events from snapshot reads of these flags report `local_evaluation_inconclusive` instead of `flag_missing`.
+- The load-time warning is logged with `Logger.Warnf`, so it shows without debug logging.

api/public-api.txt

@@ -38,6 +38,8 @@ const (
 
 	FeatureFlagErrorFlagMissing = "flag_missing"
 
+	FeatureFlagErrorLocalEvaluationInconclusive = "local_evaluation_inconclusive"
+
 	FeatureFlagErrorEvaluationFailed = "evaluation_failed"
 
 	FeatureFlagErrorQuotaLimited = "quota_limited"
@@ -551,6 +553,9 @@ func (e *FeatureFlagEvaluations) OnlyAccessed() *FeatureFlagEvaluations
 
 
 
+func (e *FeatureFlagEvaluations) UnresolvedFlags() map[string]UnresolvedFlagReason
+
+
 type FeatureFlagPayload struct {
 	Key string
 	DistinctId string
@@ -783,6 +788,8 @@ type IdentifyInApi struct {
 type InAppDecider func(frame runtime.Frame) bool
 
 type InconclusiveMatchError struct {
+
+	Reason UnresolvedFlagReason
 }
 
 func (e *InconclusiveMatchError) Error() string
@@ -852,6 +859,8 @@ type RequestContextOptions struct {
 }
 
 type RequiresServerEvaluationError struct {
+
+	Reason UnresolvedFlagReason
 }
 
 func (e *RequiresServerEvaluationError) Error() string
@@ -940,6 +949,14 @@ type Ticker struct {
 
 func (t *Ticker) Stop()
 
+type UnresolvedFlagReason string
+
+const (
+	UnresolvedFlagReasonExperienceContinuity UnresolvedFlagReason = "experience_continuity"
+	UnresolvedFlagReasonUnsupportedDefinition UnresolvedFlagReason = "unsupported_definition"
+	UnresolvedFlagReasonUnresolvedDependency UnresolvedFlagReason = "unresolved_dependency"
+	UnresolvedFlagReasonMissingContext UnresolvedFlagReason = "missing_context"
+)
 type Variants struct {
 	Variants []FlagVariant `json:"variants"`
 }

feature_flag_errors.go

@@ -24,6 +24,10 @@ const (
 	// FeatureFlagErrorFlagMissing indicates the requested flag was not in the API response
 	FeatureFlagErrorFlagMissing = "flag_missing"
 
+	// FeatureFlagErrorLocalEvaluationInconclusive indicates the flag has a loaded local
+	// definition, but neither local evaluation nor a remote fallback resolved it
+	FeatureFlagErrorLocalEvaluationInconclusive = "local_evaluation_inconclusive"
+
 	// FeatureFlagErrorEvaluationFailed indicates the flag was present but failed to evaluate due to a transient server error
 	FeatureFlagErrorEvaluationFailed = "evaluation_failed"
 

feature_flag_evaluations.go

@@ -30,6 +30,10 @@ type FeatureFlagEvaluations struct {
 	// granularity the legacy single-flag path emits.
 	errorsWhileComputing bool
 	quotaLimited         bool
+	// unresolved maps each flag with a loaded local definition that neither
+	// local evaluation nor the remote fallback resolved to the reason.
+	// Filtered snapshots leave it empty.
+	unresolved map[string]UnresolvedFlagReason
 
 	mu       sync.Mutex
 	accessed map[string]struct{}
@@ -130,6 +134,24 @@ func (e *FeatureFlagEvaluations) Keys() []string {
 	return keys
 }
 
+// UnresolvedFlags returns the flags that have a loaded local definition but
+// that neither local evaluation nor a remote fallback resolved, mapped to the
+// reason local evaluation was inconclusive. These flags are absent from Keys,
+// IsEnabled returns false and GetFlag returns nil for them. Reading this does
+// not record an access and does not fire an event. The returned map is a copy.
+//
+// Snapshots returned by Only and OnlyAccessed have no unresolved flags.
+func (e *FeatureFlagEvaluations) UnresolvedFlags() map[string]UnresolvedFlagReason {
+	if e == nil {
+		return nil
+	}
+	unresolved := make(map[string]UnresolvedFlagReason, len(e.unresolved))
+	for key, reason := range e.unresolved {
+		unresolved[key] = reason
+	}
+	return unresolved
+}
+
 // OnlyAccessed returns a filtered copy of this snapshot containing only the
 // flags that were accessed via IsEnabled or GetFlag before this call.
 //
@@ -281,8 +303,8 @@ func (e *FeatureFlagEvaluations) recordAccess(key string) {
 
 	// Build the comma-joined $feature_flag_error matching the single-flag
 	// path's granularity: response-level errors (errors-while-computing,
-	// quota-limited) are combined with per-flag errors so consumers can
-	// filter by type.
+	// quota-limited) are combined with per-flag errors (flag-missing or
+	// local-evaluation-inconclusive) so consumers can filter by type.
 	var errs []string
 	if e.errorsWhileComputing {
 		errs = append(errs, FeatureFlagErrorErrorsWhileComputing)
@@ -291,7 +313,11 @@ func (e *FeatureFlagEvaluations) recordAccess(key string) {
 		errs = append(errs, FeatureFlagErrorQuotaLimited)
 	}
 	if !found {
-		errs = append(errs, FeatureFlagErrorFlagMissing)
+		if _, unresolved := e.unresolved[key]; unresolved {
+			errs = append(errs, FeatureFlagErrorLocalEvaluationInconclusive)
+		} else {
+			errs = append(errs, FeatureFlagErrorFlagMissing)
+		}
 	} else if flag.Error != nil {
 		errs = append(errs, *flag.Error)
 	}
@@ -311,7 +337,7 @@ func (e *FeatureFlagEvaluations) recordAccess(key string) {
 
 // cloneWith builds a child snapshot with the given flag set. The accessed set
 // is copied so further access on the child does not leak back into the
-// parent's accessed set.
+// parent's accessed set. The child carries no unresolved flags.
 func (e *FeatureFlagEvaluations) cloneWith(flags map[string]evaluatedFlagRecord) *FeatureFlagEvaluations {
 	e.mu.Lock()
 	accessedCopy := make(map[string]struct{}, len(e.accessed))