feat(feature-flags)!: Evaluate ordered targeting rules

[stanleyphu]

Why

The runtime's enable-only evaluator cannot honor an ordered rule that serves false. The runtime now polls only the v2 payload and evaluates rules first-match-wins. Unknown rules/operators do not match; unparseable served values use the caller's default.

This is a breaking change for anyone reading flag configuration:

• getFlag() and change-event snapshots return rules plus off_value instead of targets. isEnabled() keeps its existing signature.
• The poll types are FlagPollEntry, FlagPollResponse ({ version: 2, flags }), FlagPollRule and FlagPollCondition. The v1 types are gone.
• v1 bootstrapFlags data is ignored and readiness still resolves. A v1 poll response is treated as malformed: the last good snapshot is kept and error is emitted. Disabled v1 targets have no v2 equivalent; they never affected evaluation.

The README describes the runtime in v2 terms.

Not covered by CI

• Before the implementation, the new boundary tests failed because polling omitted payload_version=2 and a future bootstrap envelope was cached as two flags. Both pass now.
• Exercised the built SDK's HTTP polling through a loopback relay to the already-authenticated local flags testing app, with the API on codex/auth-7096-poll-payloads. The relay forwarded live API payloads; credentials stayed inside the testing app.
• Loaded all four built entry points (Node/worker, ESM/CJS) with a stubbed fetch. Each one evaluated a v2 bootstrap with a user exclusion ahead of an organization inclusion (user false, org true, user + org false), ignored a v1 bootstrap while still resolving readiness, polled /sdk/feature-flags?payload_version=2, and kept its snapshot and emitted one error when a poll returned a v1 payload.

Proof

The live poll requested /sdk/feature-flags?payload_version=2 and loaded 16 flags. For the disposable poll-payload-smoke flag, whose user exclusion precedes its organization inclusion:

no matching target        false
matching user             false
matching organization     true
matching user + org       false

The SDK on main reads the enable-only v1 projection and returns true for the same user + org. This branch preserves the exclusion.

Fixes AUTH-7097

[linear-code]

AUTH-7097

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge as an intentional breaking release.

Summary

Changes local flag evaluation from enable-only targets to ordered rules. The first matching rule can serve false.

• Enabled flags follow the first matching rule in their list.
• The runtime polls version 2 flags and keeps its last good snapshot.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A["v2 bootstrap or poll"] --> B{"Valid payload?"}
  B -->|Yes| C["Replace cached flags"]
  B -->|No| D["Keep cached flags"]
  C --> E{"Flag enabled?"}
  E -->|No| F["Serve off_value"]
  E -->|Yes| G["Check rules in array order"]
  G -->|First match| H["Serve rule value"]
  G -->|No match| I["Serve default_value"]
  F --> J["Non-boolean values use caller default"]
  H --> J
  I --> J

Loading

_{Reviews (3) · Last reviewed commit: "refactor: Remove version suffixes from f..." · Reviewed by Greptile}

[Deborah-Digges]

How do we plan to roll this out? I imagine now that we have the v2 version of the SDK API shipped, we can just ship this without waiting for the full rollout of targeting rules.

disabled v1 targets get dropped since they don’t affect evaluation. We should call this out in the migration notes.

However, this would break existing targeting, so I'm wondering when the right order to ship this SDK change would be

[workos-shipyard]

⚓ Shipyard review suggestion

Suggested team: applied-ai, based on recent contributors to the changed files (@nicknisi).

• Assign @hadihallak · 0 assignments in the last 7 days
• Assign @jacobiajohnson · 0 assignments in the last 7 days
• Assign @meganspaulding · 0 assignments in the last 7 days
• Pick for me · balances recent workload

Links open Shipyard for confirmation. Choosing a reviewer overrides availability; “Pick for me” skips known absences.
Comment /tag <team> for a team or /tag to infer one. Tag the same team again to reroll.

Shipyard Analysis

⏳ Generating analysis...

⚓ Explore the analysis in depth in Shipyard · 🔄 Re-run analysis

[workos-shipyard]

⚓ Review requested from @nicknisi for team dx, requested by @stanleyphu.

Shipyard Analysis

⏳ Generating analysis...

⚓ Explore the analysis in depth in Shipyard · 🔄 Re-run analysis

[stanleyphu]

@greptileai review