Clean up documentation consistency

internal/normalizers/common/finalize.go

@@ -9,12 +9,12 @@ import (
 )
 
 // Finalize builds the output event envelope by copying the input and applying the
-// canonical schema/payload, plus (optionally) EffectiveAt.
+// canonical schema/payload, plus an optional effective time.
 //
 // Important behavior:
 //   - ID/Kind/Source/EmittedAt are preserved by copying the input event.
-//   - EffectiveAt is only overwritten when effectiveAt is non-zero.
-//     If effectiveAt is zero, any existing in.EffectiveAt is preserved.
+//   - EffectiveAt is only overwritten when the supplied effective time is non-zero.
+//     If the supplied time is zero, any existing in.EffectiveAt is preserved.
 //   - Payload floats are rounded to a stable wire-friendly precision (see round.go).
 func Finalize(in event.Event, outSchema string, outPayload any, effectiveAt time.Time) (*event.Event, error) {
 	// Enforce stable numeric presentation for weather payloads before delegating to feedkit's

internal/normalizers/common/json.go

@@ -15,7 +15,7 @@ import (
 //   - sources emit raw JSON payloads (typically json.RawMessage)
 //   - normalizers decode into provider structs
 //
-// Errors include a small amount of stage context ("extract payload", "decode raw payload").
+// Errors include a small amount of operation context ("extract payload", "decode raw payload").
 // Callers typically wrap these with a provider/kind label.
 func DecodeJSONPayload[T any](in event.Event) (T, error) {
 	return fknormalize.DecodeJSONPayload[T](in)
@@ -24,15 +24,15 @@ func DecodeJSONPayload[T any](in event.Event) (T, error) {
 // NormalizeJSON is a convenience wrapper for the common JSON-normalizer pattern:
 //
 //  1. Decode raw JSON payload into provider struct T
-//  2. Map T into canonical payload P (plus an EffectiveAt timestamp)
-//  3. Finalize the event envelope (schema/payload/effectiveAt) + Validate
+//  2. Map T into canonical payload P (plus an effective time)
+//  3. Finalize the event envelope (schema/payload/effective time) + Validate
 //
 // label should be short and specific, e.g. "openweather observation".
 // outSchema should be the canonical schema constant.
 // build should contain ONLY provider/domain mapping logic.
 //
 // Error policy:
-//   - NormalizeJSON wraps ALL failures with consistent context: "<label> normalize: <stage>: ..."
+//   - NormalizeJSON wraps ALL failures with consistent context: "<label> normalize: <operation>: ..."
 //   - build() should return specific errors without repeating the label prefix.
 func NormalizeJSON[T any, P any](
 	in event.Event,

internal/normalizers/nws/alerts.go

@@ -29,7 +29,7 @@ import (
 //  2. Alert timing fields are best-effort parsed; invalid timestamps do not fail the
 //     entire normalization (they are left nil).
 //  3. Some fields are intentionally passed through as strings (severity/urgency/etc.)
-//     since canonical vocabularies may evolve later.
+//     because the canonical model currently preserves provider vocabulary there.
 type AlertsNormalizer struct{}
 
 func (AlertsNormalizer) Match(e event.Event) bool {