[stanleyphu]

Stack. This is #762, split into four PRs for review. Merge them in order; after each merge I'll rebase the next one onto main.

1. chore(feature-flags): Parse and evaluate flag configurations locally #764 Configuration and evaluation ← this PR
2. feat(feature-flags): Evaluate feature flags locally with a polling runtime client #765 Sync runtime client
3. feat(feature-flags): Add an async feature flags runtime client #766 Async runtime client
4. chore(feature-flags): Keep the runtime clients safe across fork() #767 Fork safety

Description

This adds the configuration snapshot the runtime client evaluates from. It has no network code.

• FeatureFlagsConfiguration parses a v2 payload (GET /sdk/feature-flags?payload_version=2), given as any mapping, and keeps its own copy. It round-trips through JSON and pickle, so it can be cached and passed back as a bootstrap.
• Evaluation matches Node and .NET:
  • A disabled flag serves its off value.
  • Otherwise, the first rule whose conditions all match wins.
  • If no rule matches, the default value applies.
  • A context is a flat {target_type: id} mapping, so custom target types work the same way as user and organization.
• It accepts payloads that Node rejects outright, such as a flag without a default or off value, or a rule shape it doesn't know. It skips only what it can't evaluate.
• changed_flags reports which slugs a new snapshot changed, for change events.
• Context validation mirrors the API's rules for target types and IDs, and logs each distinct problem once.

Nothing is exported yet, and nothing calls this code until #765. That's why the title is chore:: it keeps this PR out of the changelog.

Where to look: start with _configuration.py (_parse_flag, _parse_rule, _CompiledFlag.evaluate), then _context.py. Of the 5,190 added lines, 4,275 are the four JSON fixture files. They're data and can be skimmed. They're shaped for the shared cross-SDK corpus (AUTH-7098).

How I checked it:

• The corpus runner (test_corpus.py) evaluates every case with both caller defaults, False and True. That tells "no answer" apart from a real False, and the runner fails on any field it doesn't recognize. The same fixtures run again through the runtime client in feat(feature-flags): Evaluate feature flags locally with a polling runtime client #765.
• nox -s ci passes locally: format, lint, pyright (0 errors) and 3,109 tests.

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes

Nothing user-facing yet. The docs follow-up is tracked on #765.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[Low impact] The PR appears safe to merge; the mapping fix leaves no identified blocking issue.

Summary

Adds local feature flag parsing, evaluation, context checks, and change detection.

• Feature-flag snapshots can be evaluated locally and compared for changes.
• Flag evaluation accepts validated IDs for built-in and custom target types.

_{Reviews (3) · Last reviewed commit: "fix(feature-flags): Accept any mapping a..." · Reviewed by Greptile}

[stanleyphu]

@greptileai review

[gjtorikian]

lgtm!