Repository navigation
Conversation
Scenarios drive a real client through its public API, with only the transport replaced: getters, a failed record, errors while computing flags, quota limiting, failed requests, bootstrap, overrides, survey-only responses, flag keys, minimal events, event controls, before_send, identity changes, the next page load, disabled flags and the oldest response shape. The fixture holds what posthog-js 1.448.0 returns, sends and stores for each scenario, recorded from this source before any change to it.
posthog-js now requests /flags/?v=4 and reads each flag's typed value, reason and rule metadata. The legacy rendering that every getter, event and stored property reads is derived from `value` in one place: a boolean as is, a string as the variant, null as false, and a number or object as true with the value as its payload. A record without `value` comes from a server that does not serve v4 and is read exactly as before; each client logs that once. The response version is a seam on the shared flags extension: a protected `_responseFormat` that returns the version to request and the reader of the response that version selects. Only posthog-js overrides it. @posthog/browser keeps requesting v=2, and its bundle does not include the reader. A typed record with a known field of the wrong JSON type is unreadable. It reads as a disabled, failed flag, and the other flags in the response are not affected. The typed value and rule metadata are stored beside the legacy members of each record in `$feature_flag_details`, so they survive a page load and merge with partial responses like the rest of the record. No stored property is added: a released posthog-js adds every stored property it does not know to each event it sends. The stored flag values, payloads and active flags are what 1.448.0 stores, so older versions that share the storage read them as before, and a record that an older version stored has no typed value. `getRemoteConfigPayload()` keeps requesting v=2: it reads only the top-level `featureFlagPayloads`. Tests read the contract fixtures that posthog-node vendors from posthog-sdk-test-harness 1.30.0, and compare every scenario of the released-behaviour recording from both response shapes.
The next page load after an upgrade reads what the released version stored: the same getter results and `$feature_flag_called` events, no typed record, and no request.
Replay incident risk checkThis diff touches code involved in past incidents. This is a heads-up, not a verdict: read the matched sections of INCIDENTS.md and answer their review questions before merging. For a judgment on whether this diff has the same failure mode, run the |
Coherence📄 0 spec file errors · ⛔ 0 broken rules · 🚪 2 unchecked inputs · 🐛 0 bugs that came back What is Coherence?Coherence compares the code with its spec files ( This check read 44 parts of the code and 7 rules. Note These findings do not make this check fail. None of these findings are in files that this pull request changes. You do not need to fix them in this pull request. 🚪 Unchecked inputs (2)
What this means and how to fix itInput from outside this code comes in at these places. The spec does not say what checks that input. 10 more places were already like this when Coherence was added. This list does not show them. To close one of these, find the place by its name in the
To get the line to add, run |
posthog-js Compliance ReportDate: 2026-11-13 16:50:49 UTC ✅ All Tests Passed!26/26 tests passed Capture Tests✅ 26/26 tests passed View Details
|
|
Size Change: +46.2 kB (+0.17%) Total Size: 27.3 MB 📦 View Changed
ℹ️ View Unchanged
|
Node SDK acceptance v2Commit: 1348554 Capture v0✅ 233 passed / ❌ 4 non-passing / Drill-down: run artifacts → ❌ server_snapshot_payload_false — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ server_snapshot_payload_zero — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ server_snapshot_payload_null — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertionFlags field differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:135 the first flags request field "geoip_disable" should equal JSON false Operation: Field: Expected: false Actual value: true Harness exit: 1; report validation exit: 1. Capture v1✅ 298 passed / ❌ 4 non-passing / Drill-down: run artifacts → ❌ server_snapshot_payload_false — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ server_snapshot_payload_zero — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ server_snapshot_payload_null — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertionFlags field differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:135 the first flags request field "geoip_disable" should equal JSON false Operation: Field: Expected: false Actual value: true Harness exit: 1; report validation exit: 1. |
SDK performance: posthog-node1 change worth reviewing: 1 observed regression. Flags require at least a 5% change in the median and all six pairs agreeing on direction. This is a noise filter, not proof of a performance change or a CI gate.
View all results
Values are medians of paired measurements. Not flagged does not mean unchanged. Unavailable means a measurement could not be provided, not zero. Estimated allocation measurements retain their instrumentation uncertainty. RSS measures the whole process, not just SDK allocations; observed peaks are sampled checkpoints. Paired ranges in the diagnostics describe variability, not confidence intervals. Each shard uses its own runner; compare Before PR against With PR within a row, not across shards. Compared 102 metric rows; 102 rows shown in all results. Omitted or shortened data remain in |
The reader assigned each rendered record to a plain object by key, so a flag keyed `__proto__` set the prototype instead of an own property and was dropped. It now builds the object with `Object.fromEntries`, as the v2 reader does.
…eader `flags-response.ts` in browser-common now mirrors `packages/node/src/flags-response.ts`: the same functions, with the same names and bodies, so that both can move to `@posthog/core` unchanged. Only its types differ, because browser-common compiles with `exactOptionalPropertyTypes`. What a browser SDK does differently stays in `flags-response-v4.ts`, which only calls the shared reader: - The parsed record is stored. Its typed members are stored with the legacy rendering under their wire names, and a stored record is read back with the shared reader, once per stored object. - A record without a typed value is stored as sent, also when a field has the wrong type. - A flag without a variant has `variant: null`, as a v2 record carries it. Stored flag state, getter results and events do not change. The ES5 entrypoint gets the `Number.isFinite` polyfill, which the shared reader uses.
…apshots The deployment compatibility snapshots record the query of each request. The four snapshots of the current core now expect `v=4` on their 135 `/flags` requests each. Nothing else in them changes, and the snapshots of the historical cores, which request `v=2`, are untouched. The check reported exactly these 540 differences. The values were edited in place, not regenerated: an update needs a full run with equal repetitions, and the Firefox replay cells currently differ between repetitions on other branches too.
…n reader again This reverts 2e2f4f8, which replaced the reader written for the browser with a copy of posthog-node's reader. The copy added about 3 KiB to the minified bundle, and its only gain was an easier later move of both readers to `@posthog/core`. One thing is kept from the copy: a v1 response with flags counts as a response without typed values, like a response with a v2 record. The ES5 entrypoint drops the `Number.isFinite` polyfill again. The browser's reader does not use it, and it uses no `Map` or `Set` constructor that takes values.
… getters The typed value and the rule metadata of a `/flags?v=4` record are stored with the flag for the SDK's own use. `getFlagsWithDetails()` and `getFeatureFlagDetails()` returned the stored record, so they showed `value`, `config_version`, `rule_type`, `rule_id`, `variant_key` and `forced_variant` at runtime, although no public type declares them. The response format now says how a stored record is returned (`publicDetail`), and both getters return the record without those members. The code that builds `$feature_flag_called` and the code that merges a partial response read the stored records, as before. Tests: - `flags-response-v4.spec.ts` loads every valid response of the contract fixtures and fails on any member of a returned record that the public types do not declare. It also covers an overridden flag, a record that another page stored, and a merged response. - The released-behaviour scenarios now read `getFlagsWithDetails()`. The recording was made again on the unchanged 1.448.0 source and differs only by that result. A new test scans every getter result, callback and event of every scenario for a typed member.
Problem
The flags service answers
/flags?v=4with a typed flag record: one typedvalue(boolean, string, number, object or null) instead ofenabledandvariant, plus a structuredreasonand rule metadata. posthog-node reads it since #5538. posthog-js still requestsv=2, so it cannot send the config version 2 flag events that the typed record makes possible. #5730, stacked on this PR, adds them.Changes
posthog-js now requests
/flags/?v=4and keeps the typed record of each flag. For a well-formed response, every getter, payload,onFeatureFlagscallback,$feature_flag_calledevent and stored flag value is the same as in 1.448.0. This ports #5538 to the browser. No public API is added.Where to look. Of the 11,100 added lines, 8,068 are a recorded JSON fixture, 540 are one changed value in the deployment snapshots, and about 2,140 are tests. The source change is about 310 lines:
packages/browser-common/src/flags-response-v4.ts(229 lines, the reader), 73 lines inpackages/browser-common/src/feature-flags.tsand 10 inpackages/browser/src/posthog-featureflags.ts./flags/?v=4instead ofv=2. A server that does not serve v4 answers with the v2 record, which is read as before, so there is no fallback request._responseFormat: the version to request and the reader of the response that version selects. Only posthog-js overrides it.@posthog/browserkeeps requestingv=2, and its bundle does not include the reader.flags-response-v4.tsis a reader written for the browser. It follows the rules of posthog-node's reader and is checked against the same contract fixtures, but it is driven by small tables of field types, which keeps the bundle small. The legacy rendering is derived fromvalue: a boolean as is, a string as the variant,nullasfalse, and a number or object astruewith the value as its payload. The existing code then reads that rendering unchanged.$feature_flag_details. No stored property is added.getFlagsWithDetails()andgetFeatureFlagDetails()return each record without them, so they return the members they returned before. Nothing else returns a stored record.posthog-jsminor,@posthog/browser-commonpatch.What users can notice:
$feature_flag_reason. Values do not change, and config version 1 flags are identical in every field./flagsby URL needv=4.This PR and #5730 should land and release together: on its own, this one reads config version 2 experiment splits but still reports them with the legacy
$feature_flag_calledonly.Bundle size (
pnpm bundle-size:array,array.jsagainstmain): +2.15 KiB minified, +0.72 KiB gzip (+0.56%). The@posthog/browserflags bundle grows by 656 B minified (189 B gzip), from the seam.A copy of posthog-node's reader replaced the browser's reader for a few commits, so that both could later move to
@posthog/coreas a plain move. It measured +4.71 KiB minified, +1.41 KiB gzip, and was taken out again (fe9839c) for that cost.Tests
released-flags.test.ts: 16 scenarios drive a real client with only the transport replaced (getters, a failed record, errors while computing flags, quota limiting, failed requests, bootstrap, overrides, survey-only responses,flag_keys, minimal events,send_event: false, opt-out,before_send, identify, group and reset, the next page load, disabled flags, the oldest response shape). The recording holds what 1.448.0 returns, sends and stores, made on unchanged source. The scenarios then run from a v2-shaped and a v4-shaped response and must match that recording.getFlagsWithDetails(), and one test scans every getter result, callback and event of every scenario for a typed member.flags-response-v4.spec.tsloads every valid response of the contract fixtures and fails on any member of a returned record that the public types do not declare. Both tests fail when the getters return the stored record.flags-response-v4.spec.ts(231 tests) checks the reader against the contract fixtures that posthog-node vendors from posthog-sdk-test-harness 1.30.0: every valid producer response, the reader corpus, wrongly typed fields, legacy parity between both shapes, how typed records merge into stored state, and what the public getters return.v=4on their 135/flagsrequests each, which are the 540 differences the check reported. The values were edited in place and the check in CI confirms them. Its Firefox replay cells currently differ between repetitions on other branches too (feat(flags): treat failed evaluations as unavailable #5693), which fails the job before it compares.@posthog/browser(660, which pinv=2), browser functional tests, lint,check-types,oxfmt --check, the public API reference check and the mangled-name check.Detail: stored state across versions, public getters, reader rules, differences from posthog-node
Stored state and other posthog-js versions
Flags are stored and read back by other page loads, other tabs and other posthog-js versions.
$feature_flag_details, which every version since that property was added keeps off events. The record then also follows the existing rules for merging, cross-tab sync and identity changes without new code.$enabled_feature_flags,$feature_flag_payloadsand$active_feature_flagsare exactly what 1.448.0 stores for the same flags, and each stored record has every member 1.448.0 stores with the same value. A test compares them with the recording for every scenario, and asserts that the set of stored properties is unchanged.valuehas no typed record. A test starts this source on the state 1.448.0 stored: same getter results and events, no typed record, no request.localStoragein jsdom, each writing for the other to read. Getter results match in both directions, the older build sends its usual$feature_flag_called, and this build sends legacy events for state the older build stored.Public getters
getFlagsWithDetails()andgetFeatureFlagDetails()return a typed record withoutvalueand withoutconfig_version,rule_type,rule_id,variant_keyandforced_variantinmetadata. A record without a typed value is returned as it is stored. The response format says how (publicDetail), so@posthog/browser, which stores no typed members, returns its records as before.$feature_flag_called, which takes the legacy members only, and by the code that merges a partial response into them.getFlagsWithDetails()returned in 1.448.0, also for overridden flags. It was made again on the unchanged 1.448.0 source and differs from the first recording only by that result.posthog.get_property('$feature_flag_details')and the browser's storage show them. That is the storage itself, not a flags API.Reader rules
valueis a typed record. A record without it is stored as sent. Each client logs once (at info level) when a response has such a record, or is a v1 response with flags.value, where null means the flag has no value.variant: nullfor a flag without a variant, as a v2 record does. The events of an overridden flag depend on it ($feature_flag_original_response), which the recording caught.errorsWhileComputingFlags, like a record the server marks failed.Differences from posthog-node
packages/node/src/flags-response.tsand shares its function names where the role is the same (readFlagRecords,readTypedRecord), but not its code. Sharing one reader through@posthog/coreis left for later.value: null, whatever it carried.$feature_flag_called. posthog-node reportsunknown_error. The browser reports only response-level errors today.getRemoteConfigPayload()keeps requestingv=2. It reads only the top-levelfeatureFlagPayloads, which is not part of the flag records. It is left as it is._crossTabPersistenceseam, so the constructor and the generated API reference do not change.Not in this PR
maindoes not already use.@posthog/browserdoes not opt in. Opting in is one overridden getter.Release info Sub-libraries affected
Libraries affected
Checklist
If releasing new changes
pnpm changesetto generate a changeset file🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Written with Claude Code, as a port of #5538 with its review decisions kept.
variant: nullrendering was found.getFlagsWithDetails()at first. They are now taken off every record a public getter returns, and the recording was extended to pin that getter to 1.448.0.__proto__was dropped by the first reader. Fixed, with a test.🤖 Generated with Claude Code