RFC: Feature Flags utility with AppConfig multi-variant support

[dreamorosi]

Status: Ready for final review. Updated November 2, 2026. The design decisions are settled from the author's side; approval of this revision is pending. See the decision summary and Agent verification.

Is this related to an existing feature request or issue?

Feature request #3754

Which area does this RFC relate to?

New Feature: Feature Flags

Summary

A Feature Flags utility for Powertools for AWS Lambda (TypeScript) covering both a local rule engine over the Powertools for Python Flag Document format and AppConfig feature flags evaluated by the AppConfig Agent. One FeatureFlags API sits over both kinds of store.

Retrieval reuses Parameters where a suitable provider exists, including the Agent support shipped in v2.35.0. Multi-variant retrieval uses the Agent's selective-flag and context protocol. The public contract distinguishes fallback values from Flag Defaults and makes result types and failure behavior explicit.

Use case

Two groups asked for this in #3754:

• Teams running Python and TypeScript functions side by side want to reuse the same AppConfig freeform Flag Documents, subject to the documented compatibility limits below.
• Teams using AppConfig feature flags want to supply per-request context and receive the selected variant and attributes without writing Agent HTTP calls themselves.

Both need explicit fallbacks when retrieval is unavailable and no undefined results. Agent-only users should not pull the AppConfigData SDK client into their bundle.

Proposal

Terms

Term	Meaning
Feature Flag	A named setting whose value can vary per request. A JSON value, not only a boolean.
Evaluation Context	Caller-supplied per-request facts: strings, finite numbers, booleans, or flat arrays of those. Never nested objects, and never read automatically from an event or the environment.
Store	A source that evaluates flags, either locally or through AppConfig. Distinct from a Parameters provider.
Flag Document	The freeform JSON document used by the local rule engine.
Flag Default	A flag's default in the Flag Document, returned when no Rule matches.
Rule	A named group of Conditions and a when_match value. The first matching Rule wins.
Condition	An Action applied to a context key and a document value.
Action	A comparison named using the Python Action vocabulary.
Variant	A normalized Agent result containing enabled, variant, and attributes.
Attribute	A named value carried by a Variant.
Fallback	The caller's default argument, returned when the flag is missing or retrieval is unavailable. Distinct from the Flag Default.

Public API

import { FeatureFlags } from '@aws-lambda-powertools/feature-flags';
import { appConfigStore } from '@aws-lambda-powertools/feature-flags/appconfig';

const flags = new FeatureFlags({
  store: appConfigStore({
    application: 'my-app',
    environment: 'prod',
    name: 'features',
  }),
});

const context = { tier: 'premium', tenantId: 'tenant-123' };

// Checked boolean result, not the literal type false.
const checkoutV2 = await flags.evaluate({
  name: 'checkout_v2',
  context,
  default: false,
});

// One store retrieval, with a fallback for each requested flag.
const { banner, limit } = await flags.evaluateMany({
  flags: { banner: 'none', limit: 10 },
  context,
});

const enabled = await flags.getEnabledFeatures({ context });

The methods are shared by every store:

• evaluate returns a resolved value or the supplied Fallback, never undefined.
• evaluateMany resolves only the requested flag names and applies independent Fallbacks. It retrieves one profile/document per batch, not once per flag. Misconfiguration throws for the call rather than returning a partial result.
• getEnabledFeatures returns names whose store results have enabled: true. It returns [] on an availability failure and throws on identifiable misconfiguration.

Primitive Fallbacks on JSON-valued stores infer widened boolean, number, or string result types. Successful results must match that primitive type; mismatches throw. A Fallback is not permission to coerce the retrieved value.

Object, array, and null Fallbacks do not describe a reliable structured type. Without a validator, their result type is JSONValue. An optional Standard Schema validator checks both the Fallback and successful result and supplies the structured output type:

// settingsSchema is a caller-supplied Standard Schema validator.
const settings = await flags.evaluate({
  name: 'settings',
  default: { theme: 'light' },
  schema: settingsSchema,
});

Batch evaluation applies the same primitive checks and optional validation per flag. An optional schemas map keyed by flag name supports typed structured batch results. The utility depends on the Standard Schema contract, not a bundled validator implementation. Result and Fallback validation must preserve the JSON-value contract and never produce undefined.

Variant-backed instances have a store-aware result type: their Fallbacks must be Variant and their results are always Variant, not a narrower type inferred from a fallback literal. These requirements are checked by TypeScript and at runtime for JavaScript callers.

Stores and ownership

Keep one FeatureFlags class, plain store objects, and factory functions. There is no store class hierarchy. The interface sketch is:

type ContextScalar = string | number | boolean;
type ContextValue = ContextScalar | ContextScalar[];
type EvaluationContext = Record<string, ContextValue>;

type StoreResult<Value = JSONValue> =
  | { found: true; value: Value; enabled: boolean }
  | { found: false };

type Store<Value = JSONValue> = {
  name: string;
  getMany(
    names: readonly string[],
    context: EvaluationContext
  ): Promise<Record<string, StoreResult<Value>>>;
  getAll(
    context: EvaluationContext
  ): Promise<Record<string, StoreResult<Value>>>;
};

Stores own evaluation and report missing flags through found: false. FeatureFlags owns Fallback selection, public result checks, and logging. evaluate requests one name through getMany; evaluateMany requests the named batch; getEnabledFeatures uses getAll. Requested names are deduplicated before transport and response-shape selection.

Factories:

• ruleEngineStore({ source, now? }): reads a Flag Document from source: () => Promise<JSONValue> and evaluates it locally. A source can wrap any Parameters provider, S3 retrieval, or a plain function.
• appConfigStore(...): wraps the SDK-based AppConfigProvider for freeform Flag Documents.
• appConfigAgentStore(...): wraps Parameters getConfig for freeform Flag Documents retrieved through the Agent.
• appConfigVariantStore(...): requests AppConfig feature flags with context and returns normalized Variants, including basic flags.

The SDK factory accepts the Parameters awsSdkV3Client and clientConfig passthrough. Agent factories accept their relevant retrieval options, including timeout. Freeform factories support a JMESPath envelope for documents embedded in a larger configuration. An envelope is not a local rule engine for Agent-selected Variants.

Internally, validation, compilation, comparisons, and evaluation are functions. A custom store is a plain object satisfying Store; it must distinguish missing flags, known availability failures, and other errors.

Failure contract

Situation	evaluate / evaluateMany	getEnabledFeatures
Missing flag	That flag's Fallback	Omit the flag
Known timeout, connection failure, throttling, or service unavailability	Fallbacks	[]
Opaque Agent 5xx response	Fallbacks	[]
Explicit authentication/access denial or identifiable configuration failure	Throw	Throw
Malformed document/response, invalid context, or failed result validation	Throw	Throw
Incompatible Action operands or unexpected custom-store error	Throw	Throw

Stores wrap known availability failures in StoreUnavailableError. The evaluator catches that category, not every exception. Missing configurations/profiles are not missing flag keys. A structured single-flag NoSuchFlag response can report a missing flag; unrelated 400 responses must not be treated as missing.

Parameters-backed adapters must preserve enough error metadata to apply this policy. Do not classify every GetParameterError as an outage or parse a human-readable error message to recover a lost status. If the existing transport loses required metadata, preserving it is an integration prerequisite, not a reason to weaken the failure contract.

The Agent can conceal configuration failures behind an opaque 500. For example, an Agent without AWS credentials returned {"Message":"Unknown internal error"}. Such responses use Fallbacks. We promise to throw for identifiable misconfiguration, not to discover causes the Agent does not expose.

With a logger, a call returning Fallbacks produces one warning, including a batch where several flags are missing. An availability failure returning [] from getEnabledFeatures is also one call-level warning. No logger means no output.

Local Flag Document and evaluation

Use Python's documented freeform shape: default, optional boolean_type, named rules, when_match, and conditions with action, key, and value. Keep the same Action vocabulary, including the IN/KEY_IN_VALUE alias pairs, time Actions, and MODULO_RANGE.

• Omitted boolean_type means true, matching Python. Non-boolean flags require boolean_type: false; do not infer it from the Flag Default.
• Evaluate named rules in object insertion order, first match wins.
• Reject array-index-style Rule names that JavaScript would reorder, such as "2" and "10". Do not silently sort them or attempt to recover order from an already-parsed object. Names such as "rule_10" preserve insertion order. This is a documented restriction relative to Python.
• Ordinary Conditions with a missing context key do not match, including negative Actions. Time Actions use their validated clock keys instead of caller context, as in Python.
• Equality and membership use strict deep JSON comparisons. Booleans are distinct from numbers; arrays compare by ordered contents; object-property order does not affect equality. Reuse commons isStrictEqual where applicable. Invalid operand combinations throw an error naming the flag, rule, key, and Action, without operand values.
• Local enabled uses commons isTruthy on the resolved value. This agrees with Python for validated JSON values: false, zero, empty strings, empty arrays/objects, and null are false; nonempty containers are true regardless of their contents. Agent enabled comes from its explicit field.
• Preserve accepted odd-but-harmless cases covered by Python's conformance baseline, such as empty documents and empty rules, with warnings rather than gratuitous new failures.

Python 3.36.0 is the comparison baseline. The original RFC's divergence table included changes that have since shipped upstream:

Behavior	Current baseline and decision
Missing keys and negative Conditions	Python 3.35.0 fixed this in #8424. Preserve non-match semantics.
Same-hour midnight rollover and malformed HH:MM	Python 3.35.0 fixed these in #8423. Use full time comparisons and anchored validation.
Validation caching	Python 3.35.0 added identity-based caching in #8426. Use content-based caching here so fresh equivalent objects and mutated objects are handled correctly.
Empty documents/rules warnings	Python 3.35.0 added these in #8427. Preserve the accepted cases.
Incompatible operands	Python 3.36.0 warns and returns a non-match following #8425. TypeScript throws.
Boolean/numeric equivalence	Python permits True == 1, including membership checks. TypeScript uses strict JSON types.
Numeric Rule names	Python preserves their written order. TypeScript rejects names that ordinary JavaScript objects reorder.
Omitted boolean_type	Python-compatible: means true.

The schema format remains shared; identical evaluation is promised only within the documented supported semantics. AppConfig's own rule language/evaluator is not rewritten to match the local engine.

Validation cache and snapshots

Validate the whole Flag Document, even when a call requests only a subset of flags. On retrieval, compare serialized document content with the last validated document without deliberately sorting keys. If unchanged, reuse the compiled rules. If changed, validate and create an owned snapshot.

Keep only the latest validated, compiled snapshot per store. This is not a retrieval cache and does not cache evaluation results by context. Equivalent fresh objects reuse validation; in-place source mutations trigger revalidation. Invalid replacement documents throw rather than silently serving the previous document.

Each evaluation captures its own snapshot so concurrent calls cannot mix documents. The cached snapshot must not be exposed through returned structured values that callers or validators could mutate. Source data is never mutated.

Time and numeric modulo

Ship all three time Actions in the first implementation using Intl.DateTimeFormat for IANA zones and no added timezone runtime dependency. Preserve the validated CURRENT_TIME, CURRENT_DATETIME, and CURRENT_DAY_OF_WEEK keys and Python's UTC default. The local store accepts an optional now: () => Date; documents do not override the clock.

Port conformance cases for inclusive endpoints, same-hour midnight rollover, valid/invalid zones, datetime formats, and daylight-saving boundaries. Correctness must be demonstrated against the current Python baseline rather than inferred from JavaScript Date defaults.

MODULO_RANGE checks a numeric remainder against inclusive START/END bounds using a validated BASE. It does not hash identifiers. Match Python's modulo behavior, including negative operands, rather than copying JavaScript % blindly. AppConfig traffic splitting is a separate service-owned algorithm; do not promise the same allocation across the two mechanisms.

Agent retrieval and Variant normalization

Minimum supported Agent version: 2.0.230173, the version used for the verification below. Verify the corresponding Lambda-extension versions and regional availability before release; observations from a standalone Agent are not proof of native Lambda-extension behavior.

• For one requested flag, use ?flag=<name> and normalize the unwrapped flag response. A successful zero-length body means that flag is missing and must be handled before JSON parsing.
• For several requested flags, fetch the whole profile with context in one request, then select the requested names locally. Normalize only requested results, so an unrelated flag does not introduce a result-validation failure into the batch.
• getAll fetches the whole profile and normalizes the flags it returns.
• No additional retrieval cache sits in front of the Agent; the Agent owns caching and polling.

Whole-profile batching is deliberate. In the tested Agent, selective multi-variant requests omit unknown flags, but a basic JSON profile returns 400 for the entire selective request when even one requested flag is absent. Fetching the whole profile preserves both one request and independent Fallbacks.

It can evaluate and transfer unrequested flags through the local HTTP connection; measure that cost for large profiles before adding a more complex recovery strategy.

type Variant = {
  enabled: boolean;
  variant: string;
  attributes: Record<string, ContextValue>;
};

Normalize _variant to variant, preserve the actual AppConfig name, and collect remaining attribute fields without leaking enabled/_variant into attributes. Missing attributes become {}.

A basic flag with no _variant becomes a Variant with the synthetic name "default", its actual enabled value, and its attributes. Do not replace an actual service-supplied variant name with the synthetic one.

import { FeatureFlags } from '@aws-lambda-powertools/feature-flags';
import {
  appConfigVariantStore,
  disabledVariant,
} from '@aws-lambda-powertools/feature-flags/appconfig';

const flags = new FeatureFlags({
  store: appConfigVariantStore({ environment: 'prod', name: 'features' }),
});

const ui = await flags.evaluate({
  name: 'ui_refresh',
  context: { tier: 'premium' },
  default: disabledVariant(),
});
// ui is Variant on success and fallback.

// default: false is a TypeScript error and is rejected at runtime.

disabledVariant() returns { enabled: false, variant: 'default', attributes: {} }. A caller can supply another valid Variant Fallback explicitly.

Agent context encoding

appConfigVariantStore supports string, finite-number, and boolean context values. Its initial API rejects arrays, nested objects, null/undefined, and nonfinite numbers before retrieval. Array rejection is a supported-API restriction, not a universal claim that every Agent expression is incapable of using arrays.

These encoding restrictions apply to remote Agent evaluation only. appConfigAgentStore retrieves a freeform document and uses the local rule engine, so it retains the local context contract.

Keys must match ^[A-Za-z_][A-Za-z0-9_.-]*$. This is a conservative supported subset. Keys are transmitted without JSON quoting; unsupported keys produce an invalid-context error identifying only the key.

JSON-quote string values and escape non-ASCII UTF-16 code units as \uXXXX; send numbers and booleans as JSON literals. Do not use percent-encoding for context values. Multiple entries can use a combined Context header with comma separators because string values are quoted:

Context: tier="pro", opted_in=true, limit=10, label="a,b"

Verification covered commas, equals signs, embedded quotes, padding, empty strings, Unicode, newlines, and multiple encoded entries. Raw commas/padding changed matching, percent-encoding was not decoded, and quoting keys did not preserve their names.

Header construction must not permit context values to inject another header or entry. Local-engine contexts do not inherit the Agent key restrictions.

Package boundary

Add @aws-lambda-powertools/feature-flags. The core evaluator and local rule engine use commons and the optional Standard Schema value-validation contract, without bundling a validator implementation. Parameters-backed stores live under /appconfig, with Parameters and JMESPath as optional peers where used. Preserve exact sibling-package pins according to repository standards.

The SDK-based factory must not cause Agent-only or custom-store imports to load the AppConfigData SDK at runtime or include it in a tree-shaken bundle. This must be verified for both supported module formats rather than assumed from optional-peer declarations.

Logging

Accept an optional logger. Without one, emit no output and do not fall back to console. Debug metadata may include the flag name, matched Rule or Flag Default selection, store name, and Variant name. Call-level warnings follow the failure contract above.

Never log context values, operand values, raw Agent response bodies, attributes, or Fallback values. Errors may identify flag/rule/key/Action names and safe failure categories; passing a raw error/cause to a logger must not circumvent this policy. No per-evaluation metrics or tracing.

Implementation phases and acceptance criteria

1. Final review of this updated RFC and confirmation of the revised contracts. Link existing upstream fixes and track follow-ups for deliberate Python differences.
2. Core package and local store, with Python 3.36.0 conformance cases and explicit tests for intentional differences.
3. SDK-backed and Agent-backed freeform stores, envelopes, documentation, and layer bundling.
4. Agent Variant store, context encoding, result typing/validation, batching, and real Lambda/AppConfig integration. This completes Feature request: Add support for multi-variant AWS AppConfig feature flags #3754.

Required verification includes:

• Missing-key and negative Conditions; strict primitive/deep equality and membership; accepted/rejected document shapes; rule priority and numeric-name rejection.
• Python truthiness for enabled-feature selection; time/DST and modulo conformance.
• Content-cache hits for equivalent objects, invalidation for mutated objects, invalid replacement documents, and isolation of snapshots and returned values.
• Primitive return checks, optional Standard Schema checks, Variant-only Fallbacks, missing attributes, and basic-flag normalization, with compile-time and runtime tests.
• One retrieval per batch, independent missing-flag Fallbacks, successful empty single responses, whole-profile results, missing resources, and malformed responses.
• Context encoding and injection prevention; early invalid-context rejection; logging without values; one warning per fallback call and silence without a logger.
• Real Lambda-extension/AppConfig behavior, live IAM/service-error observations, and the supported version/layer mapping. Record errors the Agent exposes and those it hides; do not claim local Bearer-token tests prove IAM translation.
• Agent-only/custom-store bundle checks, both module builds, documented examples, unit/type checks, and 100% coverage under repository standards.

Out of scope

• A TypeScript-native Flag Document shape or explicit priorities.
• Recovering numeric Rule-name order from already-parsed objects or introducing an order-preserving JSON parser.
• Custom Actions or comparators.
• Python's validation_exception_handler.
• Per-evaluation metrics/tracing, a hidden default store, or new default-store environment variables.
• A retrieval cache in front of the Agent.
• Additional Agent context types outside the declared supported subset.
• Claiming strict JSON comparison semantics for AppConfig's own evaluator.

Potential challenges

The design decisions are settled for this revision. The following are implementation and release checks, not unspecified fallback behavior:

• Keep the Python baseline and intentional differences explicit as upstream releases evolve.
• Demonstrate time-zone/DST conformance without silently relying on local host-zone defaults.
• Verify bundle boundaries despite optional peers and shared sub-path exports.
• Measure whole-profile batch overhead on large profiles before considering selective retrieval with retries.
• Verify the minimum Agent version against actual Lambda-extension availability and integration.
• Opaque Agent failures can conceal misconfiguration; document this limit rather than claiming status-only diagnosis.

The decision comment records the real-Agent observations, version/digest, source documentation, and limits of the local experiments. No live IAM denial, AWS service outage, or native Lambda-extension error mapping has been verified yet.

Dependencies and Integrations

• @aws-lambda-powertools/commons: core helpers, including isTruthy and isStrictEqual.
• Standard Schema's type/protocol contract for optional caller-provided result validators; no bundled validator runtime.
• @aws-lambda-powertools/parameters as an optional peer for built-in freeform stores. Agent retrieval was introduced in v2.35.0; package manifests pin the current lockstep version rather than using a range.
• @aws-lambda-powertools/jmespath as an optional peer for envelopes.
• AWS AppConfig Agent 2.0.230173+ for the declared Agent contract, with Lambda-extension availability verified before release.

Alternative solutions

• Strict Python behavior everywhere: preserves boolean/numeric equivalence and swallowed comparator errors that this design deliberately avoids.
• Local rule engine only: excludes Agent-selected variants from the original request.
• Agent wrapper only: excludes local/freeform documents and non-AppConfig sources.
• Feature Flags under Parameters: combines retrieval with evaluation instead of keeping the package responsibilities separate.
• Store class hierarchy: unnecessary; factories and plain objects provide the required variation.
• Selective retrieval for every batch: smaller local responses, but basic-profile missing flags require additional requests or loss of independent Fallbacks.
• Boolean shorthand for Variant Fallbacks: creates a union or misleading return type; retain a full Variant and helper instead.
• Infer arbitrary structured types from Fallbacks: unsound without validation; use Standard Schema where a checked structured type is required.
• Identity-only validation caching: misses in-place mutations and revalidates fresh equivalent objects.
• Order-preserving raw JSON sources: preserves numeric Rule names but expands the source/parsing contract; reject this limited case instead.
• Throw for every opaque Agent error: can defeat Fallbacks during real availability failures; opaque 5xx responses use Fallbacks with a warning.
• evaluateAll without explicit Fallbacks: replaced by evaluateMany so every requested flag has a defined fallback.

Acknowledgment

• This RFC meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Review status

• Design owner: @dreamorosi.
• Approved by: pending for this revision.
• Reviewed by: @svozza on the earlier proposal; final review requested for this revision.
• Decision summary and verification: comment.
• RFC implementation PRs: not opened yet.

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[svozza]

This all seems reasonable but I would like to see more information about the abstractions we might be creating to implement this. An issue with some utilities that we have moved away from is large class hierarchies and I want to make sure that we continue this trend.

Regarding number 2: "Should evaluateMany on the local store validate only the named flags, or the whole document?", I think we should do the whole document. Even if the flag was not yours, we should not be processing incorrect documents.

Regarding number 3: "Is a Variant Fallback acceptable, or do you want default: false to mean "disabled Variant" on Agent stores?" Could you give a code example of both behaviours so I can see a practical example?

[dreamorosi]

Thanks for the reply, and sorry for the delay.

So to your first point, I had the same thought when I was designing and I actually initially went with the function abstraction like the newer ones. I then ended up backtracking to the older implementation mainly because of the store parameter which in the class is passed as constructor parameter but that otherwise would have required either to be passed at each call site or having a factory function nested call that looks a lot like a class instantiation.

With that said, after your comment I thought of something like a middle way and instead use objects & factories rather than classes:

// Core: @aws-lambda-powertools/feature-flags
type ContextValue = string | number | boolean | Array<string | number | boolean>;
type EvaluationContext = Record<string, ContextValue>;

type StoreResult =
  | { found: true; value: JSONValue; enabled: boolean }
  | { found: false };

// A Store is a plain object, not a class to extend
type Store = {
  name: string; // for logs
  get(name: string, context: EvaluationContext): Promise<StoreResult>;
  getAll(context: EvaluationContext): Promise<Record<string, StoreResult>>;
};

class FeatureFlags {
  constructor(options: { store: Store; logger?: GenericLogger });
  evaluate<T>(options: { name: string; context?: EvaluationContext; default: T }): Promise<T>;
  evaluateMany<F extends Record<string, unknown>>(options: { flags: F; context?: EvaluationContext }): Promise<F>;
  getEnabledFeatures(options?: { context?: EvaluationContext }): Promise<string[]>;
}

// Local rule engine: a factory returning a Store, no class
const ruleEngineStore = (options: {
  source: () => Promise<JSONValue>;
  now?: () => Date;
}): Store => { /* validates once per document identity, evaluates rules */ };
// Sub-path: @aws-lambda-powertools/feature-flags/appconfig (parameters is an optional peer)
const appConfigStore = (options: {
  application?: string; environment: string; name: string;
  envelope?: string; maxAge?: number;
  awsSdkV3Client?: AppConfigDataClient; clientConfig?: AppConfigDataClientConfig;
}): Store => ruleEngineStore({ source: () => new AppConfigProvider(...).get(name, { transform: 'json', maxAge }) });

const appConfigAgentStore = (options: {
  application?: string; environment: string; name: string;
  envelope?: string; timeout?: number;
}): Store => ruleEngineStore({ source: () => getConfig(name, { ..., transform: 'json' }) });

const appConfigVariantStore = (options: {
  application?: string; environment: string; name: string; timeout?: number;
}): Store => { /* ?flag= + Context: headers, returns Variant as value, enabled from response */ };

With this one we'd only have one class (FeatureFlags), one object type (Store), four factory functions. A custom store is const myStore: Store = { name: 's3', get, getAll } or ruleEngineStore({ source: fetchFromS3 }). Internally the rule engine is a handful of pure functions (validate, evaluateFlag, comparators) rather than validator classes. I don't know if this is better, but it's definitely more streamlined so I'd not mind going with this one.

[dreamorosi]

Regarding the scope of the evaluateMany, agreed, whole document.

[dreamorosi]

On the Variant Fallback, given this:

type Variant = { enabled: boolean; variant: string; attributes: Record<string, ContextValue> };
const flags = new FeatureFlags({ store: appConfigVariantStore({ environment: 'prod', name: 'features' }) });

Option 1, Fallback is a full Variant (what the RFC proposes):

const ui = await flags.evaluate({
  name: 'ui_refresh',
  context: { email, opted_in_to_beta },
  default: { enabled: false, variant: 'default', attributes: {} },
});
// ui: Variant, always. Agent down → the object above; Agent up → whatever AppConfig selected.
if (ui.enabled) render(ui.attributes.dark_mode_support);

Option 2, default: false is sugar for "disabled Variant":

const ui = await flags.evaluate({ name: 'ui_refresh', context, default: false });
// What is typeof ui? If we honour the generic, it's boolean and `ui.attributes` is a type error.
// If we special-case the store, ui is Variant at runtime but the inferred type says boolean.
// Either way the fallback type and the success type disagree.
if (ui.enabled) ...   // TS error under option 2a; runtime fine under 2b but types lie

Option 2 is only clean if evaluate on this store ignores the generic and always returns Variant, which means the return type depends on which store the instance was built with. That's the leak we've kept out of every other signature. The cost of option 1 is one verbose literal, so I'd ship a helper:

import { disabledVariant } from '@aws-lambda-powertools/feature-flags/appconfig';
const ui = await flags.evaluate({ name: 'ui_refresh', context, default: disabledVariant() });

What do you think?

[svozza]

Regarding the factory functions, I like this approach, happy to go this way too. And for the fallback, I prefer option 1 and yeah, I think the helper is a good call too.

[dreamorosi]

Design decisions and Agent verification

The design review is complete from my side. I'm updating the RFC body to describe the current proposal rather than requiring implementers to combine the original text with this thread. This revision is ready for final review; the earlier agreement on factories and Variant fallbacks should not be read as approval of every subsequent change.

Settled contracts

• Keep one FeatureFlags class. Stores are plain objects returned by factories, not a class hierarchy.
• Require Store.getMany() and Store.getAll(). Single-flag evaluation uses a one-name getMany call; there is no separate get method.
• Fetch the whole Agent profile for multi-flag batches and filter locally. Keep selective retrieval for single flags. This preserves one retrieval per batch and independent fallbacks across both basic and multi-variant profiles.
• Variant-backed instances require full Variant fallbacks and return Variant, with compile-time and runtime checks. Provide disabledVariant(). Normalize basic flags without _variant to the synthetic variant name "default"; preserve actual AppConfig names unchanged.
• For local results, infer and check widened primitive types from fallbacks. Unvalidated structured results return JSONValue; optional Standard Schema validation supplies checked structured types.
• Return fallbacks for known availability failures and opaque Agent 5xx responses. Throw for identifiable misconfiguration, explicit authentication failures, malformed data, invalid context, result-validation failures, and unexpected custom-store errors. Opaque Agent errors can conceal misconfiguration, so we do not promise to identify every underlying cause.
• Validate the whole Flag Document. Compare document content to reuse the latest validated, compiled snapshot; do not rely on object identity, mutate source data, or cache evaluation results by context.
• Match Python's omitted boolean_type behavior: omission means true. Use commons isTruthy for local enabled-feature selection; Agent stores use the explicit enabled field.
• Use strict deep JSON equality and membership comparisons. Booleans do not equal numbers. Reject array-index-style rule names rather than silently changing their priority through JavaScript property enumeration.
• Ship the time actions and numeric MODULO_RANGE behavior with Python conformance tests. MODULO_RANGE is arithmetic, not a hashing operation.
• For Agent context, support finite numbers, booleans, and JSON-quoted strings with non-ASCII characters escaped. Restrict keys to ASCII identifiers with dots and hyphens allowed. Reject unsupported context before retrieval and never log its values.
• Set the minimum Agent version to the tested 2.0.230173.

What the real Agent returned

I ran the official ARM64 Agent image, version 2.0.230173, in isolated local-development containers using AWS's documented JSON and Ion fixture formats. No AWS resources were created.

Request	Multi-variant Ion profile	Basic JSON profile
Single known flag	200, unwrapped flag object	Same
Several known flags	200, flag-keyed object	Same
Single unknown flag	200, empty body	400, NoSuchFlag
Known and unknown flags together	200, only known flags returned	Entire request fails with 400
All requested flags unknown	200, {}	400, NoSuchFlag

This is why missing-flag detection cannot assume 404 and why selective retrieval is not the initial batch strategy. Missing local application/environment/profile paths returned 404 instead.

Basic flags have no _variant, including when mixed into an Ion profile. Missing local Bearer authorization returned 401, incorrect authorization returned 403, and malformed Ion returned 400.

A normal-mode Agent without AWS credentials returned 500 with {"Message":"Unknown internal error"}; only its logs exposed the credential failure. Status alone is therefore insufficient to classify every failure.

Context tests confirmed that JSON-quoted, ASCII-escaped values preserve commas, quotes, equals signs, padding, empty strings, Unicode, and newlines, including multiple entries in one header. Raw commas and padding silently changed matching; percent-encoding was not decoded.

Quoting keys did not preserve their names. The supported key/value subset is explicit, and array contexts are an initial API restriction rather than a claim about every possible Agent expression.

The image was pinned to sha256:993efdf6964252f9c67639b89786f2a67ff40fe7d2a999b506800dc54845928d. Setup follows the local-development documentation and feature-flag samples.

Python baseline and implementation checks

Python 3.35.0 already shipped the missing-key, time-range, validation-cache, and empty-document warning changes proposed in the original divergence table. Python 3.36.0 warns on incompatible comparator operands but still returns a non-match; our proposal throws instead. The body now distinguishes current parity from intentional differences.

Remaining work is implementation and verification: Python conformance cases, real Lambda/AppConfig integration, live IAM and service-error observations, supported Lambda-extension version mapping, bundle checks, and the repository's coverage/type checks. Local Agent tests do not establish live IAM error translation or native Lambda-extension behavior.

@svozza, could you give the revised body a final review, particularly the batching strategy, checked result types, opaque-error fallback policy, and documented Python differences?

[svozza]

LGTM!

[dreamorosi]

Package layout change, ahead of #5906

The AppConfig stores will live on two sub-paths instead of the single /appconfig described above:

• @aws-lambda-powertools/feature-flags/appconfig: appConfigStore (AWS SDK)
• @aws-lambda-powertools/feature-flags/appconfig-agent: appConfigAgentStore now, and appConfigVariantStore in Feature request: appConfigVariantStore with Variant normalization and context encoding #5907

This is how @aws-lambda-powertools/parameters already keeps the AppConfigData SDK client out of Agent-only bundles (parameters/appconfig versus parameters/appconfig-agent). With one sub-path, the SDK store's import would load the SDK for every Agent user. Getting around that would mean either a dynamic import() or setting "sideEffects": false, and nothing in the repo uses either today. A bundle test in #5906 enforces the boundary.

[dreamorosi]

Clarification on schema output, ahead of #5905

The Public API section says "Result and Fallback validation must preserve the JSON-value contract and never produce undefined." In #5905 we read it as follows:

• The JSON-value contract covers what goes into validation: the Store's value and the fallback, both of which are already JSON.
• A schema's output is whatever the caller's schema returns, so transforms such as z.string().transform((s) => new Date(s)) work. That is the reason to pass a schema at all, and it matches how Parser, Batch, and Event Handler use Standard Schema.
• "Never undefined" stays a hard guarantee: it is rejected at compile time, and at runtime a schema whose output is undefined throws FlagResultValidationError, so evaluate always returns a value.