chore: add spec traceability comments across all 17 formal-requirement specs

data/data-files/client-side-eval/basic-values.yml

@@ -1,4 +1,6 @@
 ---
+# Covers FLGEA 1.1.2: client-side SDKs surface pre-evaluated outputs (value, variationIndex, reason)
+# Covers FLGEA 1.6.3: post-evaluation returns correct variation value or default
 name: basic values - <TYPE_NAME>
 
 parameters:

data/data-files/client-side-eval/errors-wrong-type.yml

@@ -1,4 +1,8 @@
 ---
+# Covers FLGEA 1.6.3: post-evaluation type mismatch returns WRONG_TYPE error and default value
+# Covers FLGEA 1.3: evaluation reason ERROR with errorKind WRONG_TYPE
+# FLGEDETAIL 1.3.1: errorKind WRONG_TYPE when flag value does not match requested type
+# FLGEDETAIL 1.1.2: default value returned on type mismatch
 name: wrong type errors
 
 # These test are only relevant for SDKs that have variation methods for specific types

data/data-files/client-side-eval/errors.yml

@@ -1,4 +1,8 @@
 ---
+# Covers FLGEA 1.6.1: flag not found returns ERROR with errorKind FLAG_NOT_FOUND
+# FLGEDETAIL 1.2.2: reason kind ERROR when flag could not be evaluated
+# FLGEDETAIL 1.3.1: errorKind FLAG_NOT_FOUND when flag key unknown
+# FLGEDETAIL 1.1.2: default value returned when evaluation fails
 name: errors - <TYPE_NAME>
 
 skipEvaluateAllFlags: true

data/data-files/client-side-eval/reasons.yml

@@ -1,4 +1,8 @@
 ---
+# Covers FLGEA 1.3: all evaluation reason kinds (OFF, FALLTHROUGH, TARGET_MATCH, RULE_MATCH, PREREQUISITE_FAILED, ERROR)
+# FLGEDETAIL 1.2.2: reason kind values OFF, FALLTHROUGH, TARGET_MATCH, RULE_MATCH, PREREQUISITE_FAILED, ERROR
+# FLGEDETAIL 1.2.3: ruleIndex, ruleId fields for RULE_MATCH; prerequisiteKey for PREREQUISITE_FAILED; inExperiment for experiments
+# FLGEDETAIL 1.3.1: errorKind MALFORMED_FLAG and EXCEPTION
 name: evaluation reasons - <NAME>
 
 parameters:

data/data-files/server-side-eval/attribute-references.yml

@@ -1,4 +1,9 @@
 ---
+# Covers ATREF 1.2.1: plain references (no leading slash) treated as literal attribute name
+# Covers ATREF 1.2.2: ~1 escape sequence interpreted as /
+# Covers ATREF 1.2.3: ~0 escape sequence interpreted as ~
+# Also tests nested attribute traversal via pointer-style references
+# Also covers FLGEA 1.2: context attribute lookup in clause evaluation
 name: attribute references
 
 constants:

data/data-files/server-side-eval/builtin-attrs.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.2: context attribute lookup for built-in attributes
 name: built-in attributes other than kind
 
 constants:

data/data-files/server-side-eval/clause-kind-matching.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.3: clause evaluation for kind attribute
 name: clause kind matching
 
 constants:

data/data-files/server-side-eval/errors-bad-attribute-reference.yml

@@ -1,4 +1,8 @@
 ---
+# Covers ATREF 1.1.1: non-conforming strings are not valid attribute references
+# Each parameter tests a different invalid reference: missing attribute, empty path
+# component, invalid escape sequences. All must produce MALFORMED_FLAG errors.
+# Also covers FLGEA 1.6.2.3: clause returns MALFORMED_FLAG for invalid attribute reference
 name: bad attribute reference errors - <NAME>
 
 parameters:

data/data-files/server-side-eval/errors-wrong-type.yml

@@ -1,4 +1,7 @@
 ---
+# FLGEA 1.6.3.3: post-evaluation WRONG_TYPE error
+# FLGEDETAIL 1.3.1: errorKind WRONG_TYPE when flag value does not match requested type
+# FLGEDETAIL 1.1.2: default value returned on type mismatch
 name: wrong type errors
 
 # These test are only relevant for SDKs that have variation methods for specific types

data/data-files/server-side-eval/errors.yml

@@ -1,4 +1,8 @@
 ---
+# FLGEDETAIL 1.2.2: reason kind ERROR when flag could not be evaluated
+# FLGEDETAIL 1.3.1: errorKind FLAG_NOT_FOUND and MALFORMED_FLAG
+# FLGEDETAIL 1.1.2: default value returned when evaluation fails
+# FLGEDETAIL 1.1.3: variationIndex absent when default value returned
 name: evaluation failures (<TYPE_NAME>)
 
 constants:
@@ -82,6 +86,7 @@ sdkData:
       variations: [ "<TYPE_VALUE>" ]
 
 evaluations:
+  # FLGEA 1.6.1: FLAG_NOT_FOUND error
   - name: flag not found
     flagKey: no-such-flag
     context: <CONTEXT>
@@ -91,6 +96,7 @@ evaluations:
       value: <TYPE_DEFAULT>
       reason: { "kind": "ERROR", "errorKind": "FLAG_NOT_FOUND" }
 
+  # FLGEA 1.6.2.9: MALFORMED_FLAG for invalid off variation index
   - name: off variation too low
     flagKey: off-variation-too-low-<TYPE_NAME>
     context: <CONTEXT>
@@ -105,6 +111,7 @@ evaluations:
     default: <TYPE_DEFAULT>
     expect: <MALFORMED_FLAG_RESULT>
 
+  # FLGEA 1.6.2: off with undefined offVariation returns default
   - name: flag is off but has no off variation
     flagKey: no-off-variation-<TYPE_NAME>
     context: <CONTEXT>
@@ -114,6 +121,7 @@ evaluations:
       value: <TYPE_DEFAULT>
       reason: { kind: "OFF" }  # this is *not* considered a "malformed flag" condition even though it returns the default
 
+  # FLGEA 1.6.2.9: MALFORMED_FLAG for invalid fallthrough variation index
   - name: fallthrough variation too low
     flagKey: fallthrough-variation-too-low-<TYPE_NAME>
     context: <CONTEXT>
@@ -128,6 +136,7 @@ evaluations:
     default: <TYPE_DEFAULT>
     expect: <MALFORMED_FLAG_RESULT>
 
+  # FLGEA 1.6.2.9: MALFORMED_FLAG for invalid target variation index
   - name: target variation too low
     flagKey: target-match-variation-too-low-<TYPE_NAME>
     context: <CONTEXT>
@@ -142,6 +151,7 @@ evaluations:
     default: <TYPE_DEFAULT>
     expect: <MALFORMED_FLAG_RESULT>
 
+  # FLGEA 1.6.2.9: MALFORMED_FLAG for invalid rule variation index
   - name: rule variation too low
     flagKey: rule-match-variation-too-low-<TYPE_NAME>
     context: <CONTEXT>

data/data-files/server-side-eval/json-variations.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.1.2: evaluation outputs with JSON variation values
 name: JSON variations
 
 constants:

data/data-files/server-side-eval/negation-and-iteration.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.3: clause negation and value iteration
 name: clause negation and value iteration
 
 constants:

data/data-files/server-side-eval/operators-date-bad-syntax.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.4.3: date-time operators with invalid syntax
 name: operators - date - bad syntax
 
 constants:

data/data-files/server-side-eval/operators-date-bad-type.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.4.3: date-time operators with invalid type
 name: operators - date - bad type
 
 constants:

data/data-files/server-side-eval/operators-date-equal.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.4.3: date-time operators with equal values
 name: operators - date - equal
 
 constants:

data/data-files/server-side-eval/operators-date-unequal.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.4.3: date-time operators with unequal values (before, after)
 name: operators - date - unequal
 
 constants:

data/data-files/server-side-eval/operators-equality.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.4.1: equality (in operator)
 name: operators - equality (<TYPE_NAME>)
 
 constants:

data/data-files/server-side-eval/operators-numeric.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.4: numeric operators (lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual)
 name: operators - numeric
 
 constants:

data/data-files/server-side-eval/operators-semver-bad-syntax.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.4.4: semantic version invalid syntax
 name: operators - semver - bad syntax
 
 constants:

data/data-files/server-side-eval/operators-semver-bad-type.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.4.4: semantic version invalid type
 name: operators - semver - bad type
 
 constants:

data/data-files/server-side-eval/operators-semver-equal.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.4.4: semantic version equality (semVerEqual)
 name: operators - semver - equal
 
 constants:

data/data-files/server-side-eval/operators-semver-unequal.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.4.4: semantic version comparison (semVerLessThan, semVerGreaterThan)
 name: operators - semver - unequal
 
 constants:

data/data-files/server-side-eval/operators-string.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.4: string operators (startsWith, endsWith, contains, matches)
 name: operators - string
 
 constants:

data/data-files/server-side-eval/prerequisites.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.1: prerequisite evaluation
 name: prerequisites
 
 constants:

data/data-files/server-side-eval/rollout-or-experiment.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.6: rollouts and experiments
 name: rollout or experiment - <NAME>
 
 constants:

data/data-files/server-side-eval/rule-match.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.3: flag rule evaluation
 name: rule match (<TYPE_NAME>)
 
 constants:

data/data-files/server-side-eval/segment-match.yml

@@ -1,4 +1,5 @@
 ---
+  # FLGEA 1.6.2.5: segment matching
   name: segment match
 
   constants:

data/data-files/server-side-eval/segment-recursion.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.5: segment matching with circular reference detection
 name: segment recursion
 
 constants:

data/data-files/server-side-eval/target-match.yml

@@ -1,4 +1,5 @@
 ---
+# FLGEA 1.6.2.2: individual targeting (targets and contextTargets)
 name: target match
 
 constants:

data/data-files/server-side-eval/variation-value-types.yml

@@ -1,4 +1,5 @@
 ---
+  # FLGEA 1.6: evaluation algorithm across variation value types
   name: variation value types (<TYPE_NAME>)
 
   parameters:

sdktests/client_side_auto_env_attributes.go

@@ -34,7 +34,10 @@ func doClientSideAutoEnvAttributesRequestingTests(t *ldtest.T) {
 	t.Run("collisions", doClientSideAutoEnvAttributesRequestingCollisionsTests)
 }
 
-// Start tests for events
+// AUTOENVATTR 1.2.1.1: SDK must require explicit opt-in/opt-out decision for environment attributes
+// AUTOENVATTR 1.2.1.2: SDK must not add environment attributes without explicit opt-in
+// AUTOENVATTR 1.2.2.5: SDK must include envAttributesVersion in auto-env contexts
+// AUTOENVATTR 1.2.2.7: All auto-env contexts must be added to the evaluation context
 func doClientSideAutoEnvAttributesEventsNoCollisionsTests(t *ldtest.T) {
 	base := newCommonTestsBase(t, "doClientSideAutoEnvAttributesEventsNoCollisionsTests")
 	dataSystem := NewSDKDataSystem(t, nil)
@@ -112,6 +115,8 @@ func doClientSideAutoEnvAttributesEventsNoCollisionsTests(t *ldtest.T) {
 	})
 }
 
+// AUTOENVATTR 1.2.2.6: Auto-env context kinds must not be added if user-specified context of that kind exists
+// AUTOENVATTR 1.2.5.1: SDK must not alter any portion of a customer-provided context kind
 func doClientSideAutoEnvAttributesEventsCollisionsTests(t *ldtest.T) {
 	base := newCommonTestsBase(t, "doClientSideAutoEnvAttributesEventsCollisionsTests")
 	dataSystem := NewSDKDataSystem(t, nil)
@@ -175,7 +180,8 @@ func doClientSideAutoEnvAttributesEventsCollisionsTests(t *ldtest.T) {
 
 // end tests for events
 
-// start tests for streaming/polling
+// AUTOENVATTR 1.2.2.5: SDK must include envAttributesVersion in auto-env contexts
+// AUTOENVATTR 1.2.2.7: All auto-env contexts must be added to the evaluation context
 func doClientSideAutoEnvAttributesRequestingNoCollisionsTests(t *ldtest.T) {
 	base := newCommonTestsBase(t, "doClientSideAutoEnvAttributesPollNoCollisionsTests")
 	dsos := []SDKDataSystemOption{DataSystemOptionPolling(), DataSystemOptionStreaming()}
@@ -206,6 +212,8 @@ func doClientSideAutoEnvAttributesRequestingNoCollisionsTests(t *ldtest.T) {
 	}
 }
 
+// AUTOENVATTR 1.2.2.6: Auto-env context kinds must not be added if user-specified context of that kind exists
+// AUTOENVATTR 1.2.5.1: SDK must not alter any portion of a customer-provided context kind
 func doClientSideAutoEnvAttributesRequestingCollisionsTests(t *ldtest.T) {
 	base := newCommonTestsBase(t, "doClientSideAutoEnvAttributesPollCollisionsTests")
 	dsos := []SDKDataSystemOption{DataSystemOptionPolling(), DataSystemOptionStreaming()}
@@ -245,7 +253,7 @@ func doClientSideAutoEnvAttributesRequestingCollisionsTests(t *ldtest.T) {
 
 // end tests for streaming/polling
 
-// start tests for headers
+// AUTOENVATTR 1.2.5.2: ld_application id, version, and versionName sourced by priority (config > platform > SDK info)
 func doClientSideAutoEnvAttributesHeaderTests(t *ldtest.T) {
 	t.RequireCapability(servicedef.CapabilityTags)
 	base := newCommonTestsBase(t, "doClientSideAutoEnvAttributesEventsCollisionsTests")

sdktests/client_side_eval.go

@@ -23,6 +23,9 @@ func doClientSideEvalTests(t *ldtest.T) {
 	t.Run("parameterized", runParameterizedClientSideEvalTests)
 }
 
+// FLGEDETAIL 1.1.7.1: client-side reason field may be absent when not requested
+// FLGEDETAIL 1.4.4.1: client-side *variationDetail accepts (flagKey, defaultValue)
+// FLGEDETAIL 1.4.4.2: client-side *variationDetail returns synchronously
 func runParameterizedClientSideEvalTests(t *ldtest.T) {
 	// For client-side SDKs, you have to tell the SDK at initialization time whether we'll be using evaluation
 	// reasons or not. The main effect of that is the client will add a withReasons query string parameter to

sdktests/client_side_events_eval.go

@@ -254,6 +254,9 @@ func doClientSideFeatureEventTests(t *ldtest.T) {
 	})
 }
 
+// CSPE 1.2.1: prerequisite events emitted equivalent to direct evaluation
+// CSPE 1.2.3: prerequisites processed in order before the dependent flag's event
+// CSPE 1.2.4: recursive prerequisites are handled (prereq1 depends on prereq2)
 func doClientSideInOrderPrereqEventTests(t *ldtest.T) {
 	dataBuilder := mockld.NewClientSDKDataBuilder()
 	dataBuilder.

sdktests/client_side_events_summary.go

@@ -34,6 +34,8 @@ func doClientSideSummaryEventTests(t *ldtest.T) {
 	})
 }
 
+// CSSE 2.1.2.1: counters group evaluations by flag key, variation, and version
+// CSSE 2.1.1: accumulator tracks default value, count, and resulting value per counter
 func doClientSideSummaryEventBasicTest(t *ldtest.T) {
 	flag1Key := "flag1"
 	flag1Result1 := mockld.ClientSDKFlag{
@@ -112,6 +114,8 @@ func doClientSideSummaryEventBasicTest(t *ldtest.T) {
 	)
 }
 
+// CSSE 1.1.1.2: unique accumulator per unique context produces separate summary events
+// CSSE 2.1.3.1: getSummary populates context on per-context summary events
 func doClientSidePerContextSummaryEventBasicTest(t *ldtest.T) {
 	flag1Key := "flag1"
 	flag1Result1 := mockld.ClientSDKFlag{
@@ -198,6 +202,7 @@ func doClientSidePerContextSummaryEventBasicTest(t *ldtest.T) {
 	)
 }
 
+// CSSE 2.1.3.1: features include contextKinds from all evaluating context kinds
 func doClientSideSummaryEventContextKindsTest(t *ldtest.T) {
 	flag1Key := "flag1"
 	flag1Result := mockld.ClientSDKFlag{
@@ -270,6 +275,8 @@ func doClientSideSummaryEventContextKindsTest(t *ldtest.T) {
 	)
 }
 
+// CSSE 1.1.1.2: unique accumulator per unique multi-kind context
+// CSSE 2.1.3.1: contextKinds populated for per-context summary events
 func doClientSidePerContxtSummaryEventContextKindsTest(t *ldtest.T) {
 	flag1Key := "flag1"
 	flag1Result := mockld.ClientSDKFlag{
@@ -345,6 +352,7 @@ func doClientSidePerContxtSummaryEventContextKindsTest(t *ldtest.T) {
 	)
 }
 
+// CSSE 2.1.3.1: unknown flag counter sets unknown=true with no version or variation
 func doClientSideSummaryEventUnknownFlagTest(t *ldtest.T) {
 	unknownKey := "flag-x"
 	context := ldcontext.New("user-key")
@@ -380,6 +388,8 @@ func doClientSideSummaryEventUnknownFlagTest(t *ldtest.T) {
 	)
 }
 
+// CSSE 1.1.2.1: accumulators cleared after getSummaries; new flush has fresh counts
+// CSSE 3.1.1: summaries included in flushed event batch
 func doClientSideSummaryEventResetTest(t *ldtest.T) {
 	flagKey := "flag1"
 	flag1Result1 := mockld.ClientSDKFlag{
@@ -454,6 +464,9 @@ func doClientSideSummaryEventResetTest(t *ldtest.T) {
 	)
 }
 
+// CSPE 1.2.2: summary counters updated equivalent to direct evaluation of prerequisites
+// CSPE 1.2.4: recursive prerequisites generate correct summary counts
+// CSSE 2.1.2.1: prerequisite evaluations increment counters in summary event
 func doClientSideSummaryBasicPrereqTest(t *ldtest.T) {
 	topLevelKey := "flag1"
 	topLevelResult := mockld.ClientSDKFlag{
@@ -551,6 +564,8 @@ func doClientSideSummaryBasicPrereqTest(t *ldtest.T) {
 	)
 }
 
+// CSPE 1.2.1: unknown prerequisites generate unknown flag summary events (Note 1.2.1)
+// CSSE 2.1.3.1: unknown prerequisite flag sets unknown=true in counter
 func doClientSideSummaryPrereqUnknownFlagTest(t *ldtest.T) {
 	topLevelKey := "flag1"
 	topLevelResult := mockld.ClientSDKFlag{