Feature-flag registry refactor

Variant selection

The normal selection order is:

P8_SOLUTION_VARIATION
    otherwise P8_PRODUCT_VARIATION
        otherwise default

This is implemented in p8-deployments/scripts/build_utils.sh:153-154 and common.sh:467.

An unknown variant silently falls back to default. That preserves old behavior, but a typo can therefore deploy default configuration rather than fail immediately.

Backend/module builds

init_feature_flags in p8-deployments/scripts/build_utils.sh:151-185:

1. Selects the solution/product/default variant.
2. Finds the central registry through P8_FEATURE_REGISTRY_DIR or known repository-relative paths.
3. Sources feature_flags.sh.
4. Loads the selected central file.
5. Writes it to the module’s generated features/p8_features.conf.

The generated file is a build/package artifact. It is not an independently edited source file.

common.sh::read_feature_info follows the same process (p8-deployments/scripts/common.sh:465-492).

p8-digital-asset-module/build_utils.sh is now a symlink to the shared implementation instead of a 532-line copy. This removes a second copy that could drift.

Terraform deployments

Twenty-seven deployments/tfvars.sh files now use the same three calls. For example, p8-api/p8-integrations/deployments/tfvars.sh:53-59:

source "$registry_dir/feature_flags.sh"
p8_load_feature_flags "$registry_dir" "${P8_SOLUTION_VARIATION:-$variant}"
p8_export_terraform_flags "$registry_dir/terraform-mappings.conf" "p8-api/p8-integrations"

terraform-mappings.conf has 97 rows for 27 consumers. A row has this shape:

consumer|source flag|Terraform variable|type
p8-api/p8-integrations|P8_FeatureIntegrations|enable_integrations|bool

The mapping layer is explicit. It does not guess Terraform names from flag names. It also:

• fails if the source flag was not loaded;
• validates true/false for bool mappings;
• exports the exact target name expected by Terraform.

The processing engine intentionally maps several values as string, because its Terraform variables are string-typed (p8-variation-values/features/terraform-mappings.conf:80-86; p8-processing-engine/deployments/variables.tf:80-124).

Terraform packages and deploys

The packaging logic now copies the complete central feature directory, including the loader, registry metadata, and mappings (scripts/deployments/build_and_deploy.sh:501-503).

A packaged deployment uses the already-generated features/p8_features.conf; it does not try to rebuild the registry from a source checkout (p8-deployments/scripts/build_utils.sh:156-167). This is the right separation:

• build/publish: resolve the variant and generate the package file;
• install/deploy: consume the package file.

UI builds

Both UI scripts now call the shared loader and convert the generated environment variables from P8_* to REACT_APP_P8_*:

• p8-trader-ui/scripts/p8_manage_feature_files.sh:15-36
• p8-ui/scripts/p8_manage_feature_files.sh:17-58

The flow is:

central p8_<variant>_features.conf
    -> generated features/p8_features.conf
    -> variant .env file
    -> P8_* renamed to REACT_APP_P8_*
    -> webpack/rspack feature elimination

Variant-specific .env files are still appended after the central file. That means a UI .env file can still override a central value even though the new documentation says module-local overrides are prohibited.

1. Clean checkout can skip conditionally deployed modules

scripts/deployments/build_and_deploy.sh:803-806 contains:

if [ -d "../features" ]; then
  pushd ../
  init_feature_flags $mode
  popd
fi

The branch deletes tracked variant files and the features directory from many modules. On a clean checkout, ../features may not exist yet, so init_feature_flags is never called.

is_deployable_module then checks an unset feature variable (scripts/deployments/build_and_deploy.sh:731-747). For example, p8-file-manager/module_conf.yaml gates p8-file-converter on P8_FeatureDocxToPdfConverter, which is true for Carbon and CIX in the central registry. With no loaded environment variable, the converter can be treated as disabled.

The guard should be based on the central loader being available, or the orchestrator should always initialize flags before checking module conditions.

2. P8_FeatureFirmInAccount is missing but still used

develop had this flag in the central files. The current registry.csv and all eight current variant files do not contain it.

The UI still contains feature-controlled branches, for example:

• p8-ui/packages/p8-admin-ui-core/src/hooks/participants/useFirmAccounts.ts:20-32
• p8-trader-ui/src/products/trader/services/AccountBalanceService/impl/AccountBalanceServiceImpl.ts:240-248
• p8-trader-ui/src/products/admin/pages/sub-pages/RefData/EntityView/ParticipantsEntityView/FirmAccounts.tsx:221-229

Carbon and CIX previously set this flag to true; DA and most other variants used false.

The new validator misses this because its regular expression looks for a word boundary before P8_ (validate.py:15). In REACT_APP_P8_..., the preceding underscore is itself a word character. The validator also does not scan .env files.

This flag should be restored with per-variant values, or all consumers should be deliberately removed/rewritten.

3. deployment_type can become empty in system-manager Terraform

The old system-manager loader explicitly did:

export deployment_type="${P8_DEPLOYMENT_TYPE:-}"

The new loader removes that assignment (p8-system-manager/p8-system-manager-engine/deployments/tfvars.sh:51-65), but the generated Terraform file still contains:

deployment_type="$deployment_type"

at lines 201 and 213.

The shared provision script separately exports TF_VAR_deployment_type, but an explicit empty terraform.tfvars value takes precedence over that environment variable. The value is consumed by operation-cycle Lambdas as P8_DEPLOYMENT_TYPE (operation_cycle.tf:151-171 and later entries).

The old passthrough needs to be preserved or the Terraform template needs to use the shared variable consistently.

4. Some variant/module overrides changed effective behavior

Centralization removes overrides by design. The important differences found during comparison are:

• CIX P8_EnablePasswordExpiration: true in the old API/system-manager local files, now false in p8-variation-values/features/p8_cix_features.conf:24. This gates the password-expiration Lambda and schedule.
• Imperium P8_FeatureMarketDataUpdate: old API-local value false, current central value true (p8-variation-values/features/p8_imperium_features.conf:69). This now enables the market-data update API path.
• Imperium P8_FeatureFileOperations: old API-local value false, current central value true (p8-variation-values/features/p8_imperium_features.conf:57).
• CIX P8_ProductVariant: old matching-engine override was cix; current central value is carbon, while P8_SolutionVariant remains cix.

These may be intended cleanup, but they are behavior changes rather than mechanical file moves.

5. Old documentation is contradictory

Some documentation still describes per-module overrides:

• documentation/architecture.md:1499
• documentation/components.md:180
• p8-deployments/scripts/AGENTS.md:226-234 has the new model, but other nearby guidance still assumes local feature files.
• .agents/skills/product/add-variant/SKILL.md:103 still instructs contributors to create module-local feature files.

A future contributor following the old variant skill can immediately reintroduce the problem this branch is trying to remove.

Change an existing flag value

Edit only the relevant central file:

p8-variation-values/features/p8_<variant>_features.conf

Do not edit generated features/p8_features.conf files. They are recreated by builds.

Example:

# p8_cix_features.conf
P8_FeatureMarketDataUpdate=true

Remember that this one value is now shared by every consumer of the CIX registry.

Add a new flag

1. Add one assignment to all eight p8_*_features.conf files.
2. Add one row to registry.csv with the owner and default.
3. Search all consumers and use the exact same flag spelling.
4. Run the validator and shell tests.

The validator requires every variant to have the same key set and requires the default metadata value to match p8_default_features.conf (validate.py:34-106).

Add a Terraform consumer

1. Declare the Terraform variable in that consumer’s deployments/*.tf.
2. Add a row to terraform-mappings.conf:

consumer|P8_SourceFlag|terraform_variable|bool

3. Ensure that consumer’s tfvars.sh calls p8_export_terraform_flags with the exact consumer name.
4. Do not add hand-written flag-to-Terraform conversion logic to the consumer.

Use string instead of bool only when the Terraform variable is intentionally string-typed.

Add or rename a variant

The current branch hard-codes the supported variant set in validate.py:14:

VARIANTS = {"bpx", "carbon", "cix", "crypto", "da", "default", "imperium", "prediction"}

A new variant therefore needs, at minimum:

• a new central registry file;
• the variant added to VARIANTS;
• matching metadata/default values;
• module variants: participation where appropriate;
• UI/build variant files and Maven/Node variant configuration;
• per-variant system-manager config where needed;
• tests for loading and packaging.

Do not create module-local feature files for the new variant.