fix(flags): load shared definitions without a secret key

[dustinbyrne]

Problem

Like PostHog/posthog-python#1039, a worker consuming shared feature flag definitions should not need a privileged secret key. Existing initialization gates prevent that supported cache-consumer configuration from evaluating flags locally.

Changes

• Permit the configured definition cache provider to supply definitions without a secret/personal API key.
• Compute flag-derived indexes before replacing in-memory state, preserving the last valid snapshot when malformed flags fail hydration.
• Keyless consumers read the shared cache directly, without invoking the fetch-decision callback or publishing definitions. They cannot claim fetch leadership they are unable to use.
• With privileged credentials, retain the existing decision flow: false reads the cache; true fetches definitions and publishes them. Direct definition requests remain authenticated.
• Add public-entry regressions, update active credential/provider docs, and include scoped patch release metadata.

Cache-only readers bypass the shared loader specification's decision-first provider step; credentialed consumers retain that step.

The existing enableLocalEvaluation:false and disabled-client controls remain effective.

💚 How did you test it?

• pnpm turbo run test:unit --filter=posthog-node: 1,146 tests passed across 39 files; 100 focused cache/format/version tests also passed.
• pnpm turbo run check-types lint build --filter=posthog-node, scoped formatting and latest-reference generation: passed. The generated reference changes one provider-option description only.
• pnpm check:public-api: passed after committing the regenerated reference.
• Freshly built CJS and ESM public-entry smoke: cache hydration, reload, malformed-read preservation and shutdown, with zero decision callbacks, HTTP requests or provider publications.
• Shared-leadership and complete-snapshot regressions fail against the prior loader/helper and pass with the fix.

Release scope

Patch release for posthog-node. Existing signatures, capture defaults and wire formats are unchanged.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Implemented with Pi worker agents and reviewed by separate fresh-context Pi reviewers. A simplify pass covered the scoped source/tests/docs before final local validation. Human review remains required.

[github-actions]

Node SDK compliance v2

Commit: e668629
Workflow run and artifacts

Capture v0 — acceptance

✅ 5 passed / ❌ 0 non-passing / ⚠️ 812 not selected

Drill-down: run artifacts → node-v2-v0 → acceptance/report.json.diagnostics.json (match case_id below).

Harness exit: 0; report validation exit: 0.

All selected cases passed and report validation succeeded.

Capture v1 — acceptance

✅ 5 passed / ❌ 0 non-passing / ⚠️ 812 not selected

Drill-down: run artifacts → node-v2-v1 → acceptance/report.json.diagnostics.json (match case_id below).

Harness exit: 0; report validation exit: 0.

All selected cases passed and report validation succeeded.

Capture v0 — migration

✅ 55 passed / ❌ 1 non-passing / ⚠️ 101 not selected

Drill-down: run artifacts → node-v2-v0 → reports/report.json.diagnostics.json (match case_id below).

❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertion

Flags field differs

Code: flag_request_field

Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:134

the first flags request field "geoip_disable" should equal JSON false

Operation: /flags/

Field: geoip_disable

Expected:

false

Actual value:

true

Harness exit: 1; report validation exit: 1.

Capture v1 — migration

✅ 120 passed / ❌ 1 non-passing / ⚠️ 36 not selected

Drill-down: run artifacts → node-v2-v1 → reports/report.json.diagnostics.json (match case_id below).

❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertion

Flags field differs

Code: flag_request_field

Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:134

the first flags request field "geoip_disable" should equal JSON false

Operation: /flags/

Field: geoip_disable

Expected:

false

Actual value:

true

Harness exit: 1; report validation exit: 1.

A new stamphog review started for this PR — the fresh verdict replaces this approval.

[stamphog]

Not approved — escalated to a human reviewer.

Re-add the stamphog label to request another review once you have addressed this.

The disclosed change enters risky territory with no current-head independent review; MODERATE familiarity does not supply the required assurance. Request review from Hugues Pouillot, Anna Garcia, or an independent agent reviewer covering the credential boundary and provider contract before re-requesting.

• Author wrote 69% of the modified lines and has 86 merged PRs in these paths (familiarity MODERATE).
• Risky territory without independent assurance: Public API contracts — packages/node/src/client.ts and packages/node/src/extensions/feature-flags/cache.ts change the supported initialization behavior and provider callback contract by enabling cache-only local evaluation without privileged credentials and skipping fetch coordination for those clients.; Auth or security-sensitive surface — packages/node/src/extensions/feature-flags/feature-flags.ts changes credential-dependent definition loading and adds an explicit credential guard before direct definition requests.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	69L, 5F substantive, 516L/8F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1d-complex (516L, 8F, two-areas, fix)
stamphog 2.4.1		.stamphog/policy.yml @ e668629 · reviewed head e668629