Audience membership core amplitude

[joe-ayoub-segment]

Summary

This PR introduces a centralized audienceMembership resolution mechanism in actions-core and migrates 1 audience destinations to consume it.

Instead of each destination independently parsing Engage traits/properties or RETL sync-mode event names to determine add vs. remove, the Core framework now computes a typed boolean | undefined value and injects it into every action's ExecuteInput. All destination changes are gated behind per-destination feature flags with full legacy fallback.

---

Core Changes (packages/core)

New: audience-membership.ts

Centralizes the logic for resolving audience membership from raw event data:

• resolveAudienceMembership(rawData, syncMode) — top-level resolver; tries Engage first, then RETL
• engageAudienceMembership(rawData) — reads context.personas.computation_class + computation_key from identify/track events emitted by Engage
• retlAudienceMembership(rawData, syncMode) — maps RETL event names (new, updated, deleted) against the configured syncMode (add, update, upsert, mirror, delete)
• Returns true (add), false (remove), or undefined (non-audience event / indeterminate)

New: flags.ts
Adds the following flags to Core. Will be removed once the associated destinations are migrated.
FLAGS.ACTIONS_GOOGLE_EC_AUDIENCE_MEMBERSHIP
FLAGS.ACTIONS_BRAZE_COHORTS_AUDIENCE_MEMBERSHIP
FLAGS.ACTIONS_LINKEDIN_AUDIENCES_AUDIENCE_MEMBERSHIP

Updated: destination-kit/types.ts

• Exports new AudienceMembership = boolean | undefined type
• Adds optional audienceMembership?: AudienceMembershipType field to ExecuteInput — typed as AudienceMembership for perform and AudienceMembership[] for performBatch

Updated: destination-kit/action.ts

• Fixes a latent bug: syncMode values from mapping were not being validated through isSyncMode() before being passed to batch handlers

Updated: index.ts

Exports AudienceMembership, resolveAudienceMembership, and FLAGS for use by destinations.

---

Destination Changes

Amplitude Cohorts

Flag: ACTIONS_CORE_AUDIENCE_MEMBERSHIP (master flag only — amplitude has no per-destination flag; membership comes from Core unconditionally once the master flag is on)

• syncAudience/fields.ts: Removed the engage_fields nested object (which contained segment_computation_class, traits_or_properties, segment_audience_key, and segment_external_audience_id). Replaced with a single
  top-level segment_external_audience_id field. This simplifies the mapping and removes the need for each payload to carry audience key / traits data.
• syncAudience/functions.ts: send() now accepts audienceMemberships?: AudienceMembership[] and uses it to route payloads into addMap / deleteMap. Payloads with undefined membership are individually errored with
  PAYLOAD_VALIDATION_FAILED.
• syncAudience/index.ts: Destructures audienceMembership from ExecuteInput and passes it to send().

---

Unit Test Coverage

• actions-core — New audience-membership.test.ts (362 lines) covering resolveAudienceMembership, engageAudienceMembership, and retlAudienceMembership across all syncModes, event types, and edge cases
• Amplitude Cohorts — Rewrote syncAudience/tests/index.test.ts; preserved legacy behavior in new snapshot legacy-to-be-removed.test.ts.snap
• Facebook Custom Audiences — Replaced monolithic index.test.ts + fb-operations.test.ts with purpose-built suites: mirror.test.ts (961 lines), upsert.test.ts (408 lines), delete.test.ts (537 lines),
  legacy.test.ts (295 lines), functions.test.ts (342 lines), audience-creation.test.ts (135 lines), canary.test.ts (175 lines)

Tested in Staging with Facebook Custom Audiences.

[github-actions]

New required fields detected

Warning

Your PR adds new required fields to an existing destination. Adding new required settings/mappings for a destination already in production requires updating existing customer destination configuration. Ignore this warning if this PR is for a new destination with no active customers in production.

The following required fields were added in this PR:

• Destination: Amplitude Cohorts, Action Field(s):segment_external_audience_id

Add these new fields as optional instead and assume default values in perform or performBatch block.

[codecov]

Codecov Report

❌ Patch coverage is 91.17647% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.93%. Comparing base (83cfc2c) to head (0c9ff88).
⚠️ Report is 10 commits behind head on main.

Files with missing lines	Patch %	Lines
...ations/amplitude-cohorts/syncAudience/functions.ts	60.00%	4 Missing ⚠️
packages/core/src/audience-membership.ts	95.34%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3670      +/-   ##
==========================================
+ Coverage   80.49%   80.93%   +0.44%     
==========================================
  Files        1320     1373      +53     
  Lines       24433    27397    +2964     
  Branches     4987     5805     +818     
==========================================
+ Hits        19667    22175    +2508     
- Misses       3859     4311     +452     
- Partials      907      911       +4     

☔ View full report in Codecov by Sentry.
📢 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.

[joe-ayoub-segment]

• segment_external_audience_id

Not an issue. Amplitude Cohorts is a new destination.