feat(api): Add an evaluation context mapping layer

[khvn26]

Thanks for submitting a PR! Please check the boxes below:

• I have read the Contributing Guide.
• I have added information to docs/ if required so people know about the feature.
• I have filled in the "Changes" section below.
• I have filled in the "How did you test this code" section below.

Changes

Contributes to #6654

In this PR, we add a new mapping layer intended to serve all parts of Core API that are supposed to invoke flag evaluation.

The gaps we close with the new mappers include the following:

1. Identity overrides now translate to a pseudo-segment with absolute priority akin to how it's done in local evaluation.
2. We now exhibit a single authoritative way to get feature contexts for environment defaults.

In tests, we pin the behaviour that Core API maintained with ORM-based evaluation.

We also make hashing behaviour mirror Edge API for transient identities.

We're migrating to these mappers in following stacked PRs.

How did you test this code?

Added new tests.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Actions	Updated
docs	Ignored	Preview	Sep 29, 2026 9:00pm UTC
flagsmith-frontend-preview	Ignored	Preview	Sep 29, 2026 9:00pm UTC
flagsmith-frontend-staging	Ignored	Preview	Sep 29, 2026 9:00pm UTC

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 4537a757-abc8-4876-9b64-d7f729672656

📥 Commits

Reviewing files that changed from the base of the PR and between 28d7d45 and e095307.

📒 Files selected for processing (11)

• api/environments/identities/models.py
• api/evaluation/__init__.py
• api/evaluation/mappers.py
• api/evaluation/types.py
• api/features/types.py
• api/tests/conftest.py
• api/tests/unit/environments/identities/test_unit_identities_models.py
• api/tests/unit/evaluation/__init__.py
• api/tests/unit/evaluation/test_unit_evaluation_mappers.py
• api/tests/unit/util/engine_models/identities/test_unit_identities_models.py
• api/util/engine_models/identities/models.py

💤 Files with no reviewable changes (2)

• api/tests/unit/evaluation/init.py
• api/evaluation/init.py

Included review availability: Your plan provides up to 8 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The changes add public type aliases for flag-engine evaluation contexts and metadata. New mapper functions convert environment feature states, identities, traits, segments, rules and conditions into these contexts. Identity overrides map to a synthetic segment. Identity hash-key methods use the persisted id when composite-key hashing is disabled and an id is available. Unit tests cover context mapping, trait precedence, identity hashing, segment rules and multivariate variants.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🟡 Moderate · up to e0953

This change makes hashing use the stored identity ID for edge identities migrated from the database. The override-list endpoint may still hash on the identifier, so it can show a different multivariate value from the one that evaluation actually serves. Confirm or fix that path before merging. The new evaluation mapping layer itself is well covered by tests.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.84%. Comparing base (475cf8e) to head (cb0edd2).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #8573    +/-   ##
========================================
  Coverage   98.83%   98.84%            
========================================
  Files        1645     1650     +5     
  Lines       67921    68135   +214     
========================================
+ Hits        67131    67345   +214     
  Misses        790      790            

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Docker builds report

Image	Build Status	Security report
ghcr.io/flagsmith/flagsmith-e2e:pr-8573	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-api-test:pr-8573	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-frontend:pr-8573	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith-api:pr-8573	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith:pr-8573	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith-private-cloud:pr-8573	Finished ✅	Results ✅

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 5dae3463-070a-48f8-b314-f5591e4e6293

📥 Commits

Reviewing files that changed from the base of the PR and between 1cc7b76 and 28d7d45.

📒 Files selected for processing (4)

• api/environments/identities/models.py
• api/tests/unit/environments/identities/test_unit_identities_models.py
• api/tests/unit/util/engine_models/identities/test_unit_identities_models.py
• api/util/engine_models/identities/models.py

Included review availability: Your plan provides up to 8 included reviews per hour; 3 remain after this review.

[emyller]

LGTM