[AI-FSSDK] [FSSDK-12760] add localHoldouts to datafile for backward compatibility

[jaeopt]

Summary

Adds support for a new top-level localHoldouts datafile section so older SDK
versions (Gen 1 / Gen 2) ignore local holdouts safely instead of misapplying
them as global holdouts. Section membership in holdouts vs localHoldouts is
now the sole signal for holdout scope.

• Entries in holdouts are always global; includedRules on these entries is
  stripped at parse time so scope is unambiguous.
• Entries in localHoldouts are always local (rule-scoped via includedRules);
  entries missing or with empty includedRules are invalid, logged at ERROR,
  and excluded from evaluation (no fallback to global).
• Backward compatible: datafiles without a localHoldouts section continue to
  work unchanged.

Changes

• lib/project_config/project_config.ts
  • ProjectConfig.localHoldouts: Holdout[] added (defaults to []).
  • createMutationSafeDatafileCopy shallow-copies entries in both holdout
    sections so per-entry mutations (e.g. stripping includedRules) don't bleed
    into the caller's datafile.
  • parseHoldoutsConfig rewritten to partition by section membership; threads
    an optional LoggerFacade for invalid-entry diagnostics.
  • createProjectConfig and tryCreatingProjectConfig thread the logger
    through so parse-time errors are surfaced.
  • Docstrings on HoldoutConfig, getGlobalHoldouts, getHoldoutsForRule
    updated — section membership is the sole signal.
• lib/shared_types.ts — docstrings on Holdout.includedRules and
  Holdout.isGlobal updated to reflect section-driven scope.
• lib/project_config/project_config.spec.ts — existing FSSDK-12369 tests
  migrated to the two-section layout; new FSSDK-12760 suite covers
  localHoldouts parsing, backward compat, strip-and-ignore for global-section
  includedRules, caller-mutation regression, both-sections partitioning,
  invalid-entry logging (missing / null / empty), and variation map coverage.
• lib/core/decision_service/index.spec.ts — makeLocalHoldoutDatafile
  helper updated to emit local holdouts in the localHoldouts section.

Reference implementations

• Python SDK PR: [AI-FSSDK] [FSSDK-12760] Add localHoldouts datafile section for backward compat python-sdk#517
• Ruby SDK PR: [AI-FSSDK] [FSSDK-12760] Add localHoldouts datafile section ruby-sdk#400

Jira

FSSDK-12760

[coveralls]

coverage: 77.691% (-0.02%) from 77.713% — ai/jaeopt/FSSDK-12760-local-datafile into master

[Copilot]

Pull request overview

Adds a new top-level localHoldouts datafile section to clearly separate global vs rule-scoped holdouts, ensuring older SDKs ignore local holdouts safely while Gen 3+ uses section membership as the sole scope signal.

Changes:

• Update holdout parsing to partition by holdouts (global) vs localHoldouts (local), strip includedRules from global entries, and log/skip invalid local entries.
• Extend ProjectConfig with localHoldouts and a rule→holdouts lookup map, threading an optional logger for parse-time diagnostics.
• Update and expand unit tests to cover backward compatibility, partitioning behavior, mutation regression, and invalid local entry handling.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
lib/shared_types.ts	Updates holdout docstrings to reflect section-driven scope semantics.
lib/project_config/project_config.ts	Implements two-section holdout parsing, adds localHoldouts, and threads logger for diagnostics.
lib/project_config/project_config.spec.ts	Migrates/extends tests for two-section holdouts behavior and error logging.
lib/message/error_message.ts	Adds a new error message for invalid localHoldouts entries.
lib/core/decision_service/index.spec.ts	Updates test helper to emit local holdouts under localHoldouts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.