fix(flags): honor versioned local property matching

[marandaneto]

💡 Motivation and Context

Local feature flag evaluation needs to use the property_matching_version returned with definitions so Ruby agrees with the service. This follows the backend behavior and the shared SDK contract.

Intentional service-v1 compatibility correction: Missing/1 versions now use the released service's aggregate boolean truthiness instead of Ruby's previous unversioned explicit comparison. For example, a false filter matches "banana" in legacy mode. This can change existing local results even before version 2 is enabled. Unsupported version selectors also use legacy matching.

Exactly numeric version 2 uses explicit scalar equality or member equality for nonempty filter arrays. Empty filter arrays retain recursive truthiness. is_not complements exact for known properties, while missing properties remain inconclusive. Null and composite values use JSON representations with sorted object keys rather than Ruby's nil/array string conversions.

Definitions and their matching version are published together in an atomic snapshot. Person, group, mixed, recursive cohort, dependency, payload and full-result evaluation retain that snapshot across refreshes. Version-only refreshes take effect on the next evaluation. The initial empty legacy snapshot is available before polling starts.

External cache providers must store the entire snapshot, including property_matching_version and version-only updates. Older entries without the version select legacy matching. The cache provider documentation and the existing posthog-ruby patch changeset describe this requirement and the compatibility correction.

Optional shared harness coverage is related work. This PR does not opt an adapter into it.

💚 How did you test it?

• Reran ruby /Users/marandaneto/Github/posthog-ruby/vendor/bundle/ruby/4.0.0/bin/rspec -I lib spec/posthog/feature_flags_property_matching_version_spec.rb on the exact tree committed as 63d115ab09cbb40af1c8bf35c7984151a05d600a: 327 examples, 0 failures. Tests cover both operators, selectors, null/composite values, missing properties, version-only refreshes, JSON cache round trips, dependencies, asynchronous loading, 304/error retention and refresh interleavings.
• Earlier validation on the unchanged source passed RuboCop for the five changed Ruby files and the public API snapshot check. The prior repair full suite passed 1004 examples, 0 failures. The initial-publication race regression failed before its fix and passed afterward.
• git diff --check passed. The required isolated autoreview against origin/main passed on the final signed commit with no actionable findings.
• Local validation used Ruby 4.0.6 and cached gems. The CI Ruby 3.2/3.3/3.4 matrix, a fresh pinned Bundler install, gem builds and live-service end-to-end testing were not run. No CI success is claimed.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

The existing patch changeset provides the release note, including the intentional legacy behavior correction above. No generated changelog was edited.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

The existing .changeset/versioned-property-matching.md was retained. The generator was not rerun.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Pi implementation and publication agents used file inspection/editing tools, Bash, Git, GitHub CLI and the isolated autoreview helper. The human directed the versioned matching contract and publication scope. Session context is local, with no public session link available.

The implementation keeps matching metadata with definition snapshots to avoid switching semantics during an evaluation. It intentionally corrects Ruby's prior service-v1 mismatch rather than preserving that divergence. The signing retry used the existing Secretive SSH identity. This draft requires human review and does not enable auto-merge or release anything.

[github-actions]

posthog-ruby Compliance Report

Date: 2026-09-05 12:48:08 UTC
Duration: 98412ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	10ms
Format Validation.Event Has Uuid	✅	105ms
Format Validation.Event Has Lib Properties	✅	110ms
Format Validation.Distinct Id Is String	✅	106ms
Format Validation.Token Is Present	✅	107ms
Format Validation.Custom Properties Preserved	✅	108ms
Format Validation.Event Has Timestamp	✅	107ms
Retry Behavior.Retries On 503	✅	5314ms
Retry Behavior.Does Not Retry On 400	✅	2109ms
Retry Behavior.Does Not Retry On 401	✅	2109ms
Retry Behavior.Respects Retry After Header	✅	8116ms
Retry Behavior.Implements Backoff	✅	15622ms
Retry Behavior.Retries On 500	✅	5214ms
Retry Behavior.Retries On 502	✅	5211ms
Retry Behavior.Retries On 504	✅	5212ms
Retry Behavior.Max Retries Respected	✅	15723ms
Deduplication.Generates Unique Uuids	✅	112ms
Deduplication.Preserves Uuid On Retry	✅	5212ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10314ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5214ms
Deduplication.No Duplicate Events In Batch	✅	112ms
Deduplication.Different Events Have Different Uuids	✅	108ms
Compression.Sends Gzip When Enabled	✅	106ms
Batch Format.Uses Proper Batch Structure	✅	107ms
Batch Format.Flush With No Events Sends Nothing	✅	4ms
Batch Format.Multiple Events Batched Together	✅	110ms
Error Handling.Does Not Retry On 403	✅	2109ms
Error Handling.Does Not Retry On 413	✅	2109ms
Error Handling.Retries On 408	✅	5212ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	108ms
Request Payload.Flags Request Uses V2 Query Param	✅	109ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	109ms
Request Payload.Flags Request Omits Authorization Header	✅	107ms
Request Payload.Token In Flags Body Matches Init	✅	107ms
Request Payload.Groups Round Trip	✅	107ms
Request Payload.Groups Default To Empty Object	✅	107ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	108ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	108ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	107ms
Request Lifecycle.No Flags Request On Init Alone	✅	3ms
Request Lifecycle.No Flags Request On Normal Capture	✅	107ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	111ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	106ms
Retry Behavior.Retries Flags On 502	✅	244ms
Retry Behavior.Retries Flags On 504	✅	242ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	110ms

[greptile-apps]

_{Reviews (1): Last reviewed commit: "fix(flags): honor versioned local proper..." | Re-trigger Greptile}