types

const (
	AGG_COUNT          AggregationType = "AGG_COUNT"
	AGG_SUM            AggregationType = "AGG_SUM"
	AGG_AVERAGE        AggregationType = "AGG_AVERAGE"
	AGG_MIN            AggregationType = "AGG_MIN"
	AGG_MAX            AggregationType = "AGG_MAX"
	AGG_STDDEV         AggregationType = "AGG_STDDEV"
	AGG_RANGE          AggregationType = "AGG_RANGE"
	AGG_MODE_COUNT     AggregationType = "AGG_MODE_COUNT"
	AGG_ZSCORE         AggregationType = "AGG_ZSCORE"
	AGG_MEDIAN         AggregationType = "AGG_MEDIAN"
	AGG_VARIANCE       AggregationType = "AGG_VARIANCE"
	AGG_MODE           AggregationType = "AGG_MODE"
	AGG_SKEWNESS       AggregationType = "AGG_SKEWNESS"
	AGG_KURTOSIS       AggregationType = "AGG_KURTOSIS"
	AGG_DISTINCT_COUNT AggregationType = "AGG_DISTINCT_COUNT"
	AGG_PERCENTILE     AggregationType = "AGG_PERCENTILE"

	// AGG_FREQUENCY counts the non-null rows whose field equals one
	// chosen value. Params: `value` (string or number, required),
	// matched as FILTER_INCLUDE matches a value (a categorical label,
	// otherwise a number). Returns the count as a scalar; a value no row
	// holds counts 0. The modal count is AGG_MODE_COUNT. Streamable +
	// mergeable (two integer counters).
	AGG_FREQUENCY AggregationType = "AGG_FREQUENCY"

	// AGG_NULL_COUNT counts records where the field is null. Inverse of
	// AGG_COUNT, which counts records where the field is non-null. Stays
	// streamable (O(1) state per row, no buffering).
	AGG_NULL_COUNT AggregationType = "AGG_NULL_COUNT"

	// AGG_WEIGHTED_MEAN computes a weighted arithmetic mean of the
	// target field using a separately-named weight field. Params:
	// `weight_field` (string, required). Emits sum(field * w) / sum(w).
	// Streamable + mergeable via weighted Chan-Welford.
	AGG_WEIGHTED_MEAN AggregationType = "AGG_WEIGHTED_MEAN"

	// AGG_DISTINCT_SUM sums the target field ONCE PER DISTINCT KEY.
	// Params: `distinct_by` (string, required) names the key field;
	// the Aggregation's own Field names the value summed. A key seen
	// on N records contributes its value once, not N times — the
	// motivating shape is a survey weight that repeats across every
	// row a respondent produced.
	//
	// FIRST VALUE WINS: when one key carries conflicting values across
	// its records, the first value observed is the one summed and every
	// later value for that key is ignored. See the aggregator's own doc
	// comment in internal/processing/aggregator_distinct_sum.go.
	//
	// Components() additionally emits the DISTINCT COUNT alongside the
	// sum, so one operator yields both figures from one scan and the
	// two can never come from different passes over the data.
	// Streamable + mergeable (per-key maps union).
	AGG_DISTINCT_SUM AggregationType = "AGG_DISTINCT_SUM"

	// AGG_RATIO emits sum(numerator_field) / sum(denominator_field) at
	// finalize. Params: `numerator_field` + `denominator_field`. The
	// Aggregation's own Field is ignored. Streamable + mergeable (two
	// independent sums).
	AGG_RATIO AggregationType = "AGG_RATIO"

	// AGG_MAPE, AGG_RMSE and AGG_MAE score a prediction against an
	// actual: Field is the actual, params.prediction_field the
	// prediction (typically an ATTR_REG_PREDICT column). MAPE is the
	// mean of |y − ŷ| / |y| as a FRACTION (rows with y == 0 excluded and
	// counted in the n_zero_actual component), RMSE the square root of
	// the mean of (y − ŷ)², MAE the mean of |y − ŷ|. A null on either
	// side skips the row. Weighted: Σw·loss / Σw. Streamable + mergeable
	// (additive sums).
	AGG_MAPE AggregationType = "AGG_MAPE"
	AGG_RMSE AggregationType = "AGG_RMSE"
	AGG_MAE  AggregationType = "AGG_MAE"

	// AGG_CI_LOWER and AGG_CI_UPPER emit the lower / upper bound of a
	// confidence interval for the mean of the named numeric field.
	// Params: `confidence` (float, default 0.95), `method` (string,
	// default "normal"). The "normal" method uses Welford mean + sample
	// variance with z = inv_normal((1+confidence)/2); streamable +
	// mergeable. The "bootstrap" method is reserved for a buffered
	// follow-up — returns PROCESSING_CONFIG today.
	AGG_CI_LOWER AggregationType = "AGG_CI_LOWER"
	AGG_CI_UPPER AggregationType = "AGG_CI_UPPER"

	// AGG_WELFORD emits the streaming Welford-Pébaÿ triple — running
	// mean, running sample variance (n-1 denominator), and observed
	// count — over a numeric field. Returns the running mean through
	// the legacy float64 contract and the typed WelfordTriple via the
	// RichAggregator interface so overlay handlers (OVERLAY_T_CELL /
	// OVERLAY_Z_CELL) can type-switch on the moment payload
	// without re-deriving variance from raw rows. Streamable; mergeable
	// via Chan-Welford. Margin reducibility is recompute (variance does
	// not pool by addition). Field type restricted to the strict scalar
	// numeric family (u8/u16/u32/u64/f32/f64); decimal128 deferred.
	AGG_WELFORD AggregationType = "AGG_WELFORD"

	// AGG_SET_UNION reduces by bitwise OR across rows. The result is a
	// uint64 mask representing the union of every selection observed.
	// Mergeable + streamable; margin-summable for crosstab.
	AGG_SET_UNION AggregationType = "AGG_SET_UNION"

	// AGG_SET_INTERSECTION reduces by bitwise AND across rows. The
	// result mask carries a bit only when every contributing row had
	// that bit set. Mergeable + streamable, but NOT margin-reducible
	// (AND across cells ≠ AND across all rows in general) — crosstab
	// margins recompute from raw rows.
	AGG_SET_INTERSECTION AggregationType = "AGG_SET_INTERSECTION"

	// AGG_SET_FREQUENCY emits a per-element histogram. The result is
	// map[label]int — one entry per dictionary value, counting the rows
	// whose mask had that bit set. Mergeable (bin-by-bin sum) + summable
	// margin. This is the survey-friendly default ("respondents per
	// issuer"). Used as a Crosstab Cell aggregator the result is a
	// map-valued cell payload.
	AGG_SET_FREQUENCY AggregationType = "AGG_SET_FREQUENCY"

	// AGG_SET_CARDINALITY_SUM sums popcount(mask) across rows. Mergeable
	// + streamable + summable margin.
	AGG_SET_CARDINALITY_SUM AggregationType = "AGG_SET_CARDINALITY_SUM"

	// AGG_SET_CARDINALITY_AVG returns mean popcount(mask) per row.
	// Mergeable + streamable; margin = mean-reducible (needs per-cell n).
	AGG_SET_CARDINALITY_AVG AggregationType = "AGG_SET_CARDINALITY_AVG"

	// AGG_SET_DISTINCT_VALUES counts the distinct exact masks observed
	// (treats each combination as atomic). Mergeable via the union of
	// seen-mask sets.
	AGG_SET_DISTINCT_VALUES AggregationType = "AGG_SET_DISTINCT_VALUES"

	// Vector aggregators (U27). Each reads a vector input — the slot's
	// Vector (a Request.Vectors name) or inline Fields, never Field —
	// and emits one figure PER MEMBER, in member order: a JSON array
	// through the RichAggregator lift (ArrayValued). Missing data is per
	// element: a null member skips that element only. AGG_VEC_MEAN is
	// Σw·x / Σw per element (null when no row answered it), AGG_VEC_SUM
	// Σw·x per element (0 when none did). Streamable and mergeable:
	// per-merge-block sums combined in a fixed tree, so the figure is
	// bit-identical for every worker count. Refused by crosstab, Sort,
	// windows, post-tests, overlays and a chain stage that feeds another
	// stage. params.expand writes one scalar column per member,
	// "<label>[<element label>]", instead of the array — presentation
	// only, refused in the same places.
	AGG_VEC_MEAN AggregationType = "AGG_VEC_MEAN"
	AGG_VEC_SUM  AggregationType = "AGG_VEC_SUM"
)

const (
	ATTR_ZSCORE     AttributeType = "ATTR_ZSCORE"
	ATTR_TSCORE     AttributeType = "ATTR_TSCORE"
	ATTR_NORMALIZED AttributeType = "ATTR_NORMALIZED"
	ATTR_FORMULA    AttributeType = "ATTR_FORMULA"
	ATTR_PERCENTILE AttributeType = "ATTR_PERCENTILE"
	ATTR_DATE_PART  AttributeType = "ATTR_DATE_PART"

	// ATTR_REG_FITTED emits the per-row fitted value ŷᵢ = Xᵢ · β + β₀ for
	// each filter-passing record, using a regression fit computed in a
	// streaming prepass over the same record set. Two-pass: prepass folds
	// the OLS sufficient statistics, finalize freezes the coefficient
	// vector, pass 2 emits ŷᵢ. Carries its own RegressionSpec-shaped
	// fields (Target, Predictors, Penalty, Alpha, L1Ratio); refits
	// internally per attribute (Option A). Accepts any OLS penalty
	// (unpenalized, ridge, lasso, elasticnet); GLM and Bayesian fits are
	// deferred.
	ATTR_REG_FITTED AttributeType = "ATTR_REG_FITTED"

	// ATTR_REG_RESIDUAL emits the per-row residual yᵢ − ŷᵢ for each
	// filter-passing record, using the same OLS prepass machinery as
	// ATTR_REG_FITTED. Sums to ≈ 0 when the fit includes an intercept
	// (always true for unpenalized OLS) and the response is observed for
	// every contributing row.
	ATTR_REG_RESIDUAL AttributeType = "ATTR_REG_RESIDUAL"

	// ATTR_REG_LEVERAGE emits the per-row hat-matrix diagonal
	// hᵢᵢ = xᵢ · (XᵀX)⁻¹ · xᵢᵀ for each filter-passing record. Restricted
	// to unpenalized OLS — penalized leverage uses a different formula
	// (involving the regularized resolvent) and GLM leverage requires the
	// IRLS weight matrix; both deferred to Phase 9. Specs with any
	// Penalty set are rejected at factory time with PROCESSING_CONFIG.
	ATTR_REG_LEVERAGE AttributeType = "ATTR_REG_LEVERAGE"

	// ATTR_REG_PREDICT scores each row from a BOUND model — a fit named
	// in the request (ComposedRequest `fits`) — instead of refitting:
	// intercept + Σ coefficient·predictor at the fit's full precision,
	// the GLM inverse link applied on the response scale (default) or
	// not (params.scale "link"). Params {fit, terms?, scale?}; `terms`
	// scores a subset of the model's terms (the intercept only when
	// listed as "(intercept)"). The fit's predictor list is authoritative
	// and read off the slot's own columns; a null in any column the
	// score reads yields null. Row-local once bound: streamable,
	// chain / merge eligible, materialize-admissible.
	ATTR_REG_PREDICT AttributeType = "ATTR_REG_PREDICT"

	// ATTR_SET_POPCOUNT emits popcount(mask) per row as a numeric column.
	// Field must reference a set_* field. Streamable.
	ATTR_SET_POPCOUNT AttributeType = "ATTR_SET_POPCOUNT"

	// ATTR_SET_HAS emits a packed_bool per row indicating whether the
	// set field has a specific dictionary label set. Params.value names
	// the label whose bit is tested. Streamable.
	ATTR_SET_HAS AttributeType = "ATTR_SET_HAS"

	// ATTR_CODE_IN emits a packed_bool (0/1) per row: 1 when the row's
	// Field value is one of Params.codes, else 0 (a null input reads 0).
	// Accepts categorical_* (codes are dictionary labels) and u4..u64
	// (codes are whole numbers). Row-local and streamable.
	ATTR_CODE_IN AttributeType = "ATTR_CODE_IN"

	// ATTR_MAHALANOBIS emits each row's Mahalanobis distance from a
	// fitted centre across the p members of Vector / Fields: D² =
	// (x − μ)ᵀ S⁻¹ (x − μ), μ the (weighted) fit mean and S the ddof = 1
	// covariance, or (params.output "p") the χ² upper tail of D² on p
	// degrees of freedom. Two-pass: the fit folds one co-moment over the
	// filtered rows params.fit_on admits ("filtered", the default, or an
	// inline filterer list); every filtered row is scored. A null member
	// gives a null score; a singular fit or N* ≤ p nulls every score with
	// a warning.
	ATTR_MAHALANOBIS AttributeType = "ATTR_MAHALANOBIS"

	// ATTR_PC_SCORE emits each row's score on one principal component
	// (params.component, 1-based) of the p members of Vector / Fields,
	// standardized to unit variance on the fit population: the
	// eigen-decomposition of the fit's correlation (params.on, the
	// default) or covariance, with MAT_PCA's order and sign convention.
	// params.rotation "varimax" scores the component after rotating the
	// params.components leading ones (MAT_PCA's rotation). Two-pass with
	// the fitted-attribute rules of ATTR_MAHALANOBIS (fit_on, listwise,
	// null member → null, singular or N* ≤ p → every score null).
	ATTR_PC_SCORE AttributeType = "ATTR_PC_SCORE"

	// ATTR_FACTOR_SCORE emits each row's score on one common factor
	// (params.factor, 1-based) of the p members of Vector / Fields: an
	// inline MAT_FACTOR fit of the fit rows' correlation (params
	// factors, extraction, rotation, kappa, gamma — MAT_FACTOR's knobs,
	// order and sign), scored by params.method "regression" (Thurstone,
	// the default) or "bartlett" on the members standardized by the fit.
	// Two-pass with the fitted-attribute rules of ATTR_MAHALANOBIS
	// (fit_on, listwise, null member → null, singular or N* ≤ p → every
	// score null).
	ATTR_FACTOR_SCORE AttributeType = "ATTR_FACTOR_SCORE"

	// ATTR_SCALE_SCORE emits each row's rating-battery score across the
	// p members of Vector / Fields: the mean of the row's valid items
	// (params.stat "mean", the default) or the PRORATED sum, that mean ×
	// p ("sum"). params.min_valid (default p) is the fewest valid items a
	// score needs — below it the score is null, never 0. params.reverse
	// names reverse-keyed member labels, scored lo + hi − x on the
	// declared range (params.scale_min / scale_max, else the kind "scale"
	// vector's bounds; a reverse list with neither is refused). With a
	// declared range an out-of-range value is MISSING (never clamped),
	// counted and warned (PULSE_ATTR_SCALE_OUT_OF_RANGE). Row-local:
	// single pass, streamable; the weight is irrelevant.
	ATTR_SCALE_SCORE AttributeType = "ATTR_SCALE_SCORE"

	// ATTR_PROFILE_SIMILARITY emits each row's similarity to a
	// reference across the p members of Vector / Fields: params.metric
	// (a similarity-direction metric — correlation, cosine, jaccard,
	// dice, overlap; default from the vector's kind), params.reference
	// (a literal array in member order, a label map, {table, key} or
	// {table, key_field} over Extensions.ReferenceVectors, matched by
	// label) and params.min_valid (fewest complete pairs, default 1).
	// key_field is a categorical label or an unsigned integer's base-10
	// value. A row whose key_field is null or has no profile is null,
	// counted (n_reference_missing) and warned
	// (PULSE_VECTOR_REFERENCE_MISSING); a domain violation likewise
	// (PULSE_VECTOR_METRIC_DOMAIN). Row-local: single pass, streamable; the
	// weight is irrelevant. A distance metric is refused with a pointer
	// to ATTR_VEC_DISTANCE.
	ATTR_PROFILE_SIMILARITY AttributeType = "ATTR_PROFILE_SIMILARITY"

	// ATTR_VEC_DISTANCE emits each row's distance to a reference across
	// the p members of Vector / Fields: ATTR_PROFILE_SIMILARITY's params
	// with a distance-direction metric (the row-local ones, plus the
	// fitted std_euclidean and mahalanobis, whose per-member SDs /
	// covariance come from ATTR_MAHALANOBIS's fit pass — two-pass,
	// params.fit_on, weighted when a weight is in force). A similarity
	// metric is refused with a pointer to ATTR_PROFILE_SIMILARITY.
	ATTR_VEC_DISTANCE AttributeType = "ATTR_VEC_DISTANCE"
)

const (
	// ComponentsMergeable signals that the components map folds across
	// chunks via the same associative/commutative path as the scalar
	// value. Welford-family (mean / variance / sum_squares / m2),
	// sums, counts, set masks, and weighted accumulators are
	// mergeable. Per-chunk components are safe to emit and merge
	// online.
	ComponentsMergeable ComponentsMergeability = "mergeable"

	// ComponentsPartial signals that the components map merges across
	// chunks but at non-trivial allocation cost — map / set unions
	// where the fold is associative but not constant-space.
	// AGG_MODE_COUNT, AGG_MODE, AGG_DISTINCT_COUNT,
	// AGG_DISTINCT_SUM, and AGG_SET_FREQUENCY are partial. The orchestrator may stage the
	// merge at terminal flush.
	ComponentsPartial ComponentsMergeability = "partial"

	// ComponentsNone signals that the components map cannot be
	// computed from a per-chunk partial — the operator needs a
	// sorted view (or equivalent) of the full input. AGG_MEDIAN /
	// AGG_PERCENTILE are the canonical Nones. Streaming chunks omit
	// components for these operators; predict declares the slot as
	// buffered-components-only.
	ComponentsNone ComponentsMergeability = "none"
)

const (
	// CovarianceClassical is the model-based covariance every fit
	// reports without a Covariance block: σ̂²(XᵀX)⁻¹ on REG_OLS,
	// (XᵀWX)⁻¹ on REG_GLM, the NIG posterior on REG_BAYES_LINEAR.
	CovarianceClassical CovarianceType = "classical"
	// CovarianceHC0 is White's heteroskedasticity-consistent sandwich,
	// meat Σ e²·x·xᵀ.
	CovarianceHC0 CovarianceType = "hc0"
	// CovarianceHC1 is HC0 scaled by N*/(N* − k).
	CovarianceHC1 CovarianceType = "hc1"
	// CovarianceHC2 weights each squared residual by 1/(1 − h).
	CovarianceHC2 CovarianceType = "hc2"
	// CovarianceHC3 weights each squared residual by 1/(1 − h)².
	CovarianceHC3 CovarianceType = "hc3"
	// CovarianceCluster is the cluster-robust CR1 sandwich over the
	// Cluster field's levels, G/(G − 1)·(N* − 1)/(N* − k); REG_OLS reads
	// it on G − 1 df, REG_GLM and REG_BAYES_LINEAR stay normal.
	CovarianceCluster CovarianceType = "cluster"
	// CovarianceHAC is Newey–West: a Bartlett-kernel sandwich over the
	// rows ordered by OrderBy, truncated at Lags, scaled N*/(N* − k).
	CovarianceHAC CovarianceType = "hac"
)

const (
	// CrosstabNormalizeNone leaves cell values as the raw cell aggregation.
	CrosstabNormalizeNone CrosstabNormalize = "none"
	// CrosstabNormalizeRow divides each cell by its row margin (cells in a row sum to 1).
	CrosstabNormalizeRow CrosstabNormalize = "row"
	// CrosstabNormalizeColumn divides each cell by its column margin (cells in a column sum to 1).
	CrosstabNormalizeColumn CrosstabNormalize = "column"
	// CrosstabNormalizeTotal divides each cell by the grand-total margin (whole table sums to 1).
	CrosstabNormalizeTotal CrosstabNormalize = "total"
)

const (
	// CrosstabShapeMatrix returns Response.Crosstab populated with a
	// MatrixPayload (row/col axis tuples + dense cell matrix + margins).
	// Inherently buffered.
	CrosstabShapeMatrix CrosstabShape = "matrix"
	// CrosstabShapeLong returns Response.Data with one tuple per
	// (row-key, column-key) cell — the existing grouped-tuple shape any
	// consumer of grouped output already handles. Margin rows are
	// flagged via the `_margin` field when emitted.
	CrosstabShapeLong CrosstabShape = "long"
)

const (
	FEAT_LOG              FeatureType = "FEAT_LOG"
	FEAT_SQRT             FeatureType = "FEAT_SQRT"
	FEAT_BUCKETIZE        FeatureType = "FEAT_BUCKETIZE"
	FEAT_ONE_HOT          FeatureType = "FEAT_ONE_HOT"
	FEAT_DATE_FEATURES    FeatureType = "FEAT_DATE_FEATURES"
	FEAT_FREQUENCY_ENCODE FeatureType = "FEAT_FREQUENCY_ENCODE"
	FEAT_TARGET_ENCODE    FeatureType = "FEAT_TARGET_ENCODE"
	FEAT_TRAIN_TEST_SPLIT FeatureType = "FEAT_TRAIN_TEST_SPLIT"
	FEAT_POLY             FeatureType = "FEAT_POLY"
)

const (
	FILTER_INCLUDE    FiltererType = "FILTER_INCLUDE"
	FILTER_EXCLUDE    FiltererType = "FILTER_EXCLUDE"
	FILTER_RANGE      FiltererType = "FILTER_RANGE"
	FILTER_EXPRESSION FiltererType = "FILTER_EXPRESSION"

	// FILTER_NULL keeps or drops records based on null state of a field.
	// Mode is "is_null" (keep null-valued records) or "is_not_null" (keep
	// non-null records). Row-local; streamable.
	FILTER_NULL FiltererType = "FILTER_NULL"

	// FILTER_TRUE keeps records where Field is logically true. Default
	// (strict) mode requires Field to be packed_bool and keeps records
	// whose value is 1. Opt-in JavaScript-style truthiness coercion is
	// enabled with Values=["truthy"]; in that mode any field type is
	// accepted and the same rules JS uses for `Boolean(value)` apply
	// (0, NaN, empty string, null → falsy; everything else → truthy).
	// Row-local; streamable.
	FILTER_TRUE FiltererType = "FILTER_TRUE"

	// FILTER_FALSE keeps records where Field is logically false. Default
	// (strict) mode requires Field to be packed_bool and keeps records
	// whose value is 0. Opt-in JavaScript-style falsiness coercion is
	// enabled with Values=["truthy"]; in that mode any field type is
	// accepted and records whose value would coerce to falsy under
	// `Boolean(value)` are kept (0, NaN, empty string, null → kept).
	// Row-local; streamable.
	FILTER_FALSE FiltererType = "FILTER_FALSE"

	// FILTER_SET_CONTAINS_ANY keeps records whose set mask shares at
	// least one bit with the resolved query mask (row & q != 0).
	FILTER_SET_CONTAINS_ANY FiltererType = "FILTER_SET_CONTAINS_ANY"

	// FILTER_SET_CONTAINS_ALL keeps records whose set mask has every bit
	// in the resolved query mask set (row & q == q).
	FILTER_SET_CONTAINS_ALL FiltererType = "FILTER_SET_CONTAINS_ALL"

	// FILTER_SET_CONTAINS_NONE keeps records whose set mask shares no
	// bits with the resolved query mask (row & q == 0).
	FILTER_SET_CONTAINS_NONE FiltererType = "FILTER_SET_CONTAINS_NONE"

	// FILTER_SET_EQUALS keeps records whose set mask exactly equals the
	// resolved query mask.
	FILTER_SET_EQUALS FiltererType = "FILTER_SET_EQUALS"

	// FILTER_DATE_RANGES keeps records whose `date` Field falls inside any
	// of a validated set of labeled date ranges (the shared E1-S1 model),
	// dropping every other row and every null date. Ranges ride the
	// structured Params slot (`{ranges: [{label, start, end}]}`); the
	// label is irrelevant to keep/drop but is still fully validated
	// (overlap/duplicate/empty/invalid). Row-local; streamable.
	FILTER_DATE_RANGES FiltererType = "FILTER_DATE_RANGES"
)

const (
	GROUP_CATEGORY GroupType = "GROUP_CATEGORY"
	GROUP_ROUNDED  GroupType = "GROUP_ROUNDED"
	GROUP_RANGE    GroupType = "GROUP_RANGE"
	GROUP_QUANTILE GroupType = "GROUP_QUANTILE"
	GROUP_DATE     GroupType = "GROUP_DATE"

	// GROUP_DATE_RANGES buckets each date row by a validated set of
	// labeled date ranges (inline {label, start, end} specs). The bucket
	// key is the matching range's label; rows outside every range land in
	// a configurable unmatched bucket (default label "unmatched").
	// Streamable + mergeable (each row maps independently to one bucket).
	GROUP_DATE_RANGES GroupType = "GROUP_DATE_RANGES"

	// GROUP_SET_VALUE treats the set mask as an atomic value. Each
	// distinct mask is its own bucket; the bucket key is the sorted
	// pipe-delimited label list (e.g. "AMEX|VISA"). One row → one
	// bucket. Streamable + mergeable.
	GROUP_SET_VALUE GroupType = "GROUP_SET_VALUE"

	// GROUP_SET_PER_ELEMENT explodes the set: each row fans into one
	// bucket per set bit, keyed by the resolved dictionary label. One
	// row → N buckets (where N = popcount(mask)). Cardinality multiplies.
	// Streamable via the multi-key streaming hook (KeysForRow on
	// StreamingGrouper). This is the survey-friendly default
	// ("respondents per option").
	GROUP_SET_PER_ELEMENT GroupType = "GROUP_SET_PER_ELEMENT"

	// GROUP_KMEANS segments records into params.k clusters by seeded,
	// deterministic k-means over the p members of Vector / Fields
	// (Euclidean; z-scored by default). Keys are cluster_1..cluster_k,
	// numbered by descending cluster size and emitted in that order; a
	// row with a null member is skipped (n_null). Buffered and
	// non-mergeable: the fit needs every row.
	GROUP_KMEANS GroupType = "GROUP_KMEANS"
)

const (
	LabelModeReplace LabelMode = "replace"
	LabelModeAugment LabelMode = "augment"
)

const (
	// LookupMultiplicityAssertUnique is the default (the zero value —
	// an unset Multiplicity resolves to this mode). internal/service.Lookup
	// fails with errors.PULSE_LOOKUP_AMBIGUOUS when the matched key
	// resolves to more than one row-id; a single match still succeeds
	// normally.
	LookupMultiplicityAssertUnique LookupMultiplicity = "assert_unique"

	// LookupMultiplicityFirst explicitly opts into "take the lowest
	// row-id" without the assert-unique failure mode — never errors on
	// a multi-row match. Row order is ascending row-id, so "first"
	// picks deterministically.
	LookupMultiplicityFirst LookupMultiplicity = "first"

	// LookupMultiplicityAll returns every matched row-id's record in
	// LookupResult.Rows, ascending row-id order, instead of a single
	// entry.
	LookupMultiplicityAll LookupMultiplicity = "all"
)

const (
	// MarginAggregationFaultNilEntry marks a nil element in the slot —
	// reachable from JSON as a literal null.
	MarginAggregationFaultNilEntry MarginAggregationFaultKind = "nil_entry"

	// MarginAggregationFaultMissingType marks an entry with no
	// aggregation Type. There is no default auxiliary aggregator.
	MarginAggregationFaultMissingType MarginAggregationFaultKind = "missing_type"

	// MarginAggregationFaultDuplicateLabel marks an effective label
	// claimed twice — by two auxiliary entries, or by an auxiliary
	// entry and the cell aggregation whose own margin already occupies
	// it.
	MarginAggregationFaultDuplicateLabel MarginAggregationFaultKind = "duplicate_label"
)

const (
	// MarginAxisRow targets the row-margin vector (Σ over columns per
	// row key).
	MarginAxisRow MarginAxis = "row"

	// MarginAxisColumn targets the column-margin vector (Σ over rows
	// per column key).
	MarginAxisColumn MarginAxis = "column"

	// MarginAxisGrand targets the grand-total margin (Σ over every
	// filter-passing row).
	MarginAxisGrand MarginAxis = "grand"
)

const (
	// MarginSummable means the margin equals the sum of cell values
	// (count, sum, null_count, frequency).
	MarginSummable MarginReducibility = "summable"
	// MarginMeanReducible means the margin is derivable only when each
	// cell also carries its observation count (average, ratio).
	MarginMeanReducible MarginReducibility = "mean_reducible"
	// MarginIndependent means the operator maintains its own margin
	// accumulator — the margin is neither a sum of cells nor a re-scan
	// (distinct_count, distinct_sum). Admitted by the fused gate: the
	// margin is already exact after one pass.
	MarginIndependent MarginReducibility = "independent"
	// MarginRecompute means the margin cannot be derived from cells and
	// must be recomputed over the raw filter-passing rows (median,
	// stddev, percentile, mode, ...).
	MarginRecompute MarginReducibility = "recompute"
)

const (
	// MatrixEncodingFull emits every row in full: Values[r] has p
	// entries. The default.
	MatrixEncodingFull MatrixEncoding = "full"
	// MatrixEncodingUpper emits the upper triangle, diagonal included:
	// Values[r] has p − r entries, Values[r][k] being cell (r, r + k).
	MatrixEncodingUpper MatrixEncoding = "upper"
)

const (
	// MatrixKindSquareSymmetric is a p × p matrix whose rows and
	// columns are the same members in the same order, with
	// Values[r][c] == Values[c][r]. Two square matrices are keyed by
	// something else: MAT_FACTOR's auxiliary.factor_correlation (the
	// factors "F1" … "Fk", always written full) and MAT_DISTANCE's
	// primary (the between grouper's bucket labels, in the spec's
	// encoding).
	MatrixKindSquareSymmetric MatrixKind = "square_symmetric"
	// MatrixKindRectangular is a p × k matrix whose rows are the
	// members (RowKeys) and whose columns are something else
	// (ColumnKeys: MAT_PCA's components "PC1" … "PCk"; MAT_FACTOR's
	// factors "F1" … "Fk"; MAT_COLLINEARITY's dimensions "D1" … "Dk", whose uncentered
	// variance decomposition also leads its rows with the intercept,
	// RowKeys "(intercept)" then the members) — or, on MAT_DISTANCE's
	// auxiliary.centroids, a k × p matrix whose rows are the bucket
	// labels and whose columns are the members. It is always
	// written full — Values[r] has k entries — whatever the spec's
	// Encoding asks (upper applies to a symmetric matrix only), and k
	// may be 0 (Values rows empty).
	MatrixKindRectangular MatrixKind = "rectangular"
)

const (
	// MAT_COVARIANCE is the covariance matrix of the members:
	// M2 / (W − ddof), params.ddof ∈ {0, 1} (default 1).
	// params.missing "listwise" (default: a row with any member null is
	// skipped) or "pairwise" (each pair over its own rows). Weighted
	// under frequency and probability weights (denominator Σw − ddof).
	MAT_COVARIANCE MatrixType = "MAT_COVARIANCE"
	// MAT_CORRELATION is the Pearson correlation matrix of the members:
	// C_ij / √(M2_ii·M2_jj), clamped to [−1, 1], the TEST_PEARSON_R
	// arithmetic. Listwise or pairwise (params.missing). A member with
	// zero spread has no defined correlation: its row and column
	// (diagonal included) are NaN (null on the wire). Weighted under frequency and probability weights
	// (r is scale-free, so the two kinds agree). No p-values.
	MAT_CORRELATION MatrixType = "MAT_CORRELATION"
	// MAT_PARTIAL_CORRELATION is the partial correlation matrix: each
	// pair's correlation with other fields held fixed, read off the
	// precision matrix of the members' Pearson correlations.
	// params.control "all" (default: each pair controls for every other
	// member) or a list of numeric fields (members or not; each output
	// pair controls for exactly those, and the output covers the
	// non-control members). A decomposition operator: a non-PSD input
	// (pairwise) is refused with PULSE_MATRIX_NOT_PSD unless
	// params.repair "nearest"; a singular one is PULSE_MATRIX_SINGULAR.
	// Weighted under frequency and probability weights. No p-values.
	MAT_PARTIAL_CORRELATION MatrixType = "MAT_PARTIAL_CORRELATION"
	// MAT_RELIABILITY is a battery's scale reliability: Cronbach's alpha
	// (raw and standardized), McDonald's omega from a one-factor minres
	// fit, the mean inter-item correlation and per-item diagnostics
	// (corrected item-total r, alpha if deleted, mean, sd), with the
	// inter-item correlation matrix as primary. params.reverse names
	// reverse-keyed items, flipped x' = scale_min + scale_max − x per
	// row before the fold (the range is required with it). At least 2
	// items; omega needs 3 and a positive-semidefinite input (or
	// params.repair "nearest"), and is null with a warning otherwise.
	// Weighted under frequency and probability weights. No p-values.
	MAT_RELIABILITY MatrixType = "MAT_RELIABILITY"
	// MAT_PCA is a principal component analysis of the members'
	// correlation (params.on "correlation", the default) or covariance
	// ("covariance") matrix: the primary is the p × k loadings
	// (eigenvector · √λ, MatrixKindRectangular, one column per retained
	// component), auxiliary.eigenvectors the p × k unit eigenvectors;
	// vectors carry every eigenvalue, the explained and cumulative
	// variance shares, the communalities and per-member KMO (MSA);
	// scalars KMO, Bartlett's sphericity test and the retained count.
	// params.components: an integer k, "kaiser" (λ > 1; the default on
	// a correlation, refused on a covariance) or {"variance": share};
	// required on a covariance. A decomposition operator (the shared
	// PSD guard, params.repair "nearest"). Sign and order follow
	// linalg.SymEigen. Weighted under frequency and probability
	// weights. No rotation.
	MAT_PCA MatrixType = "MAT_PCA"
	// MAT_COLLINEARITY is a collinearity check of the members as
	// regression predictors (no response): the primary is their
	// correlation matrix R; vectors carry each member's variance
	// inflation factor VIF = diag(R⁻¹) and tolerance 1/VIF (car::vif),
	// and Belsley's condition indices; auxiliary.variance_decomposition
	// is Belsley's variance-decomposition proportions
	// (MatrixKindRectangular: a row per variable, a column per
	// dimension); scalars condition_number (the largest condition
	// index) and max_vif (the largest VIF).
	// Belsley runs on the scaled, uncentered predictors with an
	// intercept by default (perturb::colldiag), rebuilt from the
	// co-moment as W(Σ + μμᵀ); params.center true runs it on the
	// centered predictors (R) instead. A decomposition operator (the
	// shared PSD guard, params.repair "nearest"); a singular R is
	// PULSE_MATRIX_SINGULAR. Weighted under frequency and probability
	// weights. No p-values.
	MAT_COLLINEARITY MatrixType = "MAT_COLLINEARITY"
	// MAT_FACTOR is an exploratory factor analysis of the members'
	// correlation matrix: params.factors k (an integer, or "kaiser",
	// the default: the eigenvalues of R above 1) common factors
	// extracted by params.extraction "minres" (the default, the
	// minimum-residual fit, psych fm = "minres"), "principal_axis"
	// (iterated principal axes, psych fm = "pa") or "ml" (maximum
	// likelihood, stats::factanal; adds the likelihood chi-square, TLI,
	// RMSEA with its interval at params.conf_level and BIC scalars),
	// each from the squared multiple
	// correlations, then rotated by params.rotation "none"
	// (the default), "varimax", "promax" (params.kappa, default 4) or
	// "oblimin" (params.gamma, default 0). The primary is the p × k
	// rotated loadings (MatrixKindRectangular, columns "F1" … "Fk");
	// auxiliary.unrotated the unrotated loadings (rotated runs) and
	// auxiliary.factor_correlation the k × k factor correlation
	// (oblique rotations only); vectors carry the communalities,
	// uniquenesses and the variance each factor accounts for; scalars
	// the root-mean-square residual, the empirical residual chi-square
	// (not a likelihood test), KMO, Bartlett's sphericity test and the
	// fit's iterations / convergence. A k the battery cannot identify,
	// (p − k)² < p + k, nulls the fit with PULSE_MATRIX_NOT_IDENTIFIED;
	// a uniqueness at or below 0 is reported as is with
	// PULSE_MATRIX_HEYWOOD. A decomposition operator (the shared PSD
	// guard, params.repair "nearest"). Weighted under frequency and
	// probability weights.
	MAT_FACTOR MatrixType = "MAT_FACTOR"
	// MAT_DISTANCE is the k × k distance matrix between the centroids of
	// the buckets a grouper (params.between: any built-in grouper but
	// the date family, GROUP_KMEANS included) cuts the rows into. A
	// centroid is the bucket's (weighted) mean of every member; the
	// primary is square symmetric, keyed by the bucket labels in the
	// grouper's emission order, with a zero diagonal. params.metric is
	// a linalg/metric registry name the MAT_DISTANCE consumer accepts:
	// "euclidean" (the default), "sq_euclidean", "manhattan",
	// "chebyshev", "cosine", "hellinger", "aitchison" or "mahalanobis"
	// (the pooled within-bucket covariance); params.standardize
	// z-scores the members over the bucketed rows first; params.min_valid
	// (default 1) is the fewest complete member pairs a distance needs.
	// An undefined coordinate is dropped pairwise, the element sums
	// rescaled by p/p_observed. Rows the grouper puts in no bucket (a null
	// key) are excluded and counted. vectors.sizes carries each
	// bucket's mass, auxiliary.centroids the k × p centroids. Listwise
	// only. Streamable and mergeable when the grouper is (one co-moment
	// per bucket); otherwise buffered and serial. Weighted under
	// frequency and probability weights (a GROUP_KMEANS between under
	// frequency weights only).
	MAT_DISTANCE MatrixType = "MAT_DISTANCE"
)

const (
	// MultiplicityFamilyLayer corrects one overlay layer's p-values
	// together. The overlay default.
	MultiplicityFamilyLayer MultiplicityFamily = "layer"
	// MultiplicityFamilyRow corrects each row of one MATRIX overlay
	// layer separately.
	MultiplicityFamilyRow MultiplicityFamily = "row"
	// MultiplicityFamilyColumn corrects each column of one MATRIX
	// overlay layer separately.
	MultiplicityFamilyColumn MultiplicityFamily = "column"
	// MultiplicityFamilyRequest pools one Request's tests, post-tests
	// and `request`-family overlays. The test default.
	MultiplicityFamilyRequest MultiplicityFamily = "request"
	// MultiplicityFamilyCompose pools every `compose`-family member
	// across a ComposedRequest's slots and its Compose-host overlay
	// layers. Valid only inside Compose.
	MultiplicityFamilyCompose MultiplicityFamily = "compose"
	// MultiplicityFamilyMatrix corrects the p-values of one matrix
	// result together: the off-diagonal upper-triangle cells of a
	// square_symmetric matrix (m = p(p-1)/2 for p members — the
	// diagonal and the mirrored lower triangle are not separate
	// hypotheses), every cell of a rectangular one; one family per
	// group bucket on a grouped request. The matrix spec default; valid
	// only on a MatrixSpec's block.
	MultiplicityFamilyMatrix MultiplicityFamily = "matrix"
)

const (
	// MultiplicityMethodNone applies no correction: the explicit
	// opt-out.
	MultiplicityMethodNone MultiplicityMethod = "none"
	// MultiplicityMethodBonferroni multiplies every p by the family
	// size m (family-wise error).
	MultiplicityMethodBonferroni MultiplicityMethod = "bonferroni"
	// MultiplicityMethodHolm is Holm's step-down procedure (family-wise
	// error, uniformly more powerful than Bonferroni).
	MultiplicityMethodHolm MultiplicityMethod = "holm"
	// MultiplicityMethodBH is the Benjamini-Hochberg step-up procedure
	// (false discovery rate under independence or positive dependence).
	MultiplicityMethodBH MultiplicityMethod = "bh"
	// MultiplicityMethodBY is the Benjamini-Yekutieli step-up procedure
	// (false discovery rate under arbitrary dependence).
	MultiplicityMethodBY MultiplicityMethod = "by"
)

const (
	// OverlayKindChiSqMatrix emits a whole-matrix χ² independence test
	// across the row × column contingency table built from the host
	// crosstab cells. MATRIX scope over a MATRIX (crosstab) host with
	// SCALAR payload — the layer carries a single chi-square statistic
	// plus its degrees of freedom and the corresponding p-value, all
	// surfaced through OverlaySummary (Statistic / PValue / Parameters
	// {"df"}). First inferential overlay kind and first SCALAR-shape
	// Crosstab overlay; establishes the SCALAR payload plumbing pattern
	// the remaining inferential kinds and the post-test family reuse.
	//
	// Math:
	//
	//	expected[r,c] = row_margin[r] * col_margin[c] / grand_total
	//	chisq         = Σ_{r,c} (observed[r,c] - expected[r,c])² / expected[r,c]
	//	df            = (rows - 1) * (cols - 1)
	//	p_value       = 1 - chi2_cdf(chisq, df)
	//
	// Implementation reuses the χ² survival helper that backs TEST_CHISQ
	// (internal/processing/test_stat.go chiSquareSurvival) so the overlay and the
	// row-test surface produce identical p-values for the same
	// contingency.
	//
	// Absent-cell policy: a structurally absent host cell (Present=false)
	// is treated as an observed count of 0 — the matrix shape stays
	// rectangular, the row / column / grand margins continue to drive
	// the expected-count recurrence, and an absent observation does not
	// invent a count. The handler documents the policy alongside the
	// runtime dispatch.
	//
	// Low-expected-count warning: when any expected[r,c] < 5 the handler
	// emits a single PULSE_OVERLAY_EXPECTED_LOW warning (canonical χ²
	// low-count heuristic; mirrors PULSE_TEST_EXPECTED_COUNT_TOO_LOW on
	// the TEST_CHISQ surface). The canonical
	// errors.PULSE_OVERLAY_EXPECTED_LOW constant is the source of truth.
	//
	// Scope is MATRIX (not CELL) because the test is whole-table; the
	// validator rejects any other scope. The Ref union is left empty —
	// the test is implicit-margin (uses the host's row / column / grand
	// margins inline), so callers supplying a Ref.Margin (or any other
	// ref-family pointer) get PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE.
	//
	// Inherently buffered because the host crosstab path is always
	// buffered (margins recomputed from raw rows).
	OverlayKindChiSqMatrix OverlayKind = "OVERLAY_CHISQ_MATRIX"

	// OverlayKindChiSqRow emits a per-row χ² goodness-of-fit test
	// across the host crosstab's row × column contingency table. ROW
	// scope over a MATRIX (crosstab) host with SERIES payload — one
	// per-row entry carrying the row's χ² statistic, degrees of
	// freedom (cols - 1), and p-value via OverlaySummary
	// {Statistic, PValue, Parameters{"df"}}. First SERIES-shape
	// Crosstab overlay; establishes the SeriesPayload entries
	// plumbing pattern that the remaining series families reuse.
	//
	// Math (per row r):
	//
	//	observed[c] = host.Cell(r, c)
	//	expected[c] = row_margin[r] * col_margin[c] / grand_total
	//	chisq_r    = Σ_c (observed[c] - expected[c])² / expected[c]
	//	df          = cols - 1
	//	p_value     = chi2_survival(chisq_r, df)   // = 1 - chi2_cdf
	//
	// Tests whether each row's observed column distribution differs
	// from the expected distribution derived from column margins under
	// independence. The χ² survival helper (chiSquareSurvival) is the
	// same helper that backs TEST_CHISQ and the CHISQ_MATRIX overlay —
	// overlay surfaces produce identical p-values for the same
	// contingency.
	//
	// Absent-cell policy: a structurally absent host cell (Present=
	// false) is treated as an observed count of 0 (matches the
	// CHISQ_MATRIX policy). The per-row recurrence still consumes
	// every column slot; an absent observation does not collapse the
	// column count.
	//
	// Low-expected-count warning: when any expected[c] < 5 in row r
	// the handler emits ONE PULSE_OVERLAY_EXPECTED_LOW warning per
	// offending row (not per cell — the row is the diagnostic unit
	// for goodness-of-fit). Canonical errors.PULSE_OVERLAY_EXPECTED_LOW
	// constant.
	//
	// Scope is ROW (not CELL or MATRIX) because each row's test is
	// independent — the validator rejects any other scope. The Ref
	// union is left empty — the test is implicit-margin (uses the
	// host's row / column / grand margins inline), so callers
	// supplying a Ref.Margin (or any other ref-family pointer) get
	// PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE.
	//
	// Inherently buffered because the host crosstab path is always
	// buffered (margins recomputed from raw rows).
	OverlayKindChiSqRow OverlayKind = "OVERLAY_CHISQ_ROW"

	// OverlayKindChiSqCol emits a per-column χ² goodness-of-fit test
	// across the host crosstab's row × column contingency table. COLUMN
	// scope over a MATRIX (crosstab) host with SERIES payload — one
	// per-column entry carrying the column's χ² statistic, degrees of
	// freedom (rows - 1), and p-value via OverlaySummary
	// {Statistic, PValue, Parameters{"df"}}. Mechanical column-axis twin
	// of OVERLAY_CHISQ_ROW; mirrors the SeriesPayload entries plumbing
	// pattern (Entries[i].Key == host ColumnKeys[i] element-for-element).
	//
	// Math (per column c):
	//
	//	observed[r] = host.Cell(r, c)
	//	expected[r] = row_margin[r] * col_margin[c] / grand_total
	//	chisq_c    = Σ_r (observed[r] - expected[r])² / expected[r]
	//	df          = rows - 1
	//	p_value     = chi2_survival(chisq_c, df)   // = 1 - chi2_cdf
	//
	// Tests whether each column's observed row distribution differs
	// from the expected distribution derived from row margins under
	// independence. The χ² survival helper (chiSquareSurvival) is the
	// same helper that backs TEST_CHISQ and the CHISQ_MATRIX / CHISQ_ROW
	// overlays — overlay surfaces produce identical p-values for the
	// same contingency.
	//
	// Absent-cell policy: a structurally absent host cell (Present=
	// false) is treated as an observed count of 0 (matches the
	// CHISQ_MATRIX / CHISQ_ROW policy). The per-column recurrence still
	// consumes every row slot; an absent observation does not collapse
	// the row count.
	//
	// Low-expected-count warning: when any expected[r] in column c is
	// below 5 the handler emits ONE PULSE_OVERLAY_EXPECTED_LOW warning
	// per offending column (not per cell — the column is the diagnostic
	// unit for goodness-of-fit). Canonical
	// errors.PULSE_OVERLAY_EXPECTED_LOW constant.
	//
	// Scope is COLUMN (not CELL, ROW, or MATRIX) because each column's
	// test is independent — the validator rejects any other scope. The
	// Ref union is left empty — the test is implicit-margin (uses the
	// host's row / column / grand margins inline), so callers supplying
	// a Ref.Margin (or any other ref-family pointer) get
	// PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE.
	//
	// Inherently buffered because the host crosstab path is always
	// buffered (margins recomputed from raw rows).
	OverlayKindChiSqCol OverlayKind = "OVERLAY_CHISQ_COL"

	// OverlayKindChiSqVsPop emits a single scalar χ² goodness-of-fit
	// statistic + p-value comparing the host Facet subset distribution
	// against the resolved population distribution. GROUP scope over a
	// FACET (FacetSchema) host with SCALAR payload — the layer carries
	// the chi-square statistic plus degrees of freedom and the
	// corresponding p-value via OverlaySummary{Statistic, PValue,
	// Parameters{"df"}}. A FACET-host overlay (siblings:
	// OVERLAY_INDEX_VS_POP, OVERLAY_ZSCORE_VS_POP) and the first
	// inferential FACET-host kind. Pairs with the
	// MATRIX-host CHISQ family (CHISQ_MATRIX / CHISQ_ROW / CHISQ_COL) as
	// the canonical χ² family — the viz developer renders the SCALAR
	// statistic as a goodness-of-fit badge near the facet header.
	//
	// Math:
	//
	//	subset_N      = sum(host counts)              // discrete arm only
	//	pop_freq[v]   = FacetPopulationView.DiscreteFrequency(v)
	//	expected[v]   = pop_freq[v] * subset_N        // expected scaled to subset N
	//	observed[v]   = host.Discrete.Values[v].Count
	//	chisq         = Σ_v (observed[v] - expected[v])² / expected[v]
	//	df            = len(observed) - 1
	//	p_value       = chiSquareSurvival(chisq, df)  // = 1 - chi2_cdf
	//
	// Discrete arm only: χ² goodness-of-fit requires categorical buckets
	// to form the observed × expected contingency. A numeric host (no
	// discrete payload) emits zero entries and surfaces a coded
	// PROCESSING_INTERNAL error carrying
	// PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE — the predict-time
	// validator rejects numeric hosts before runtime, so this arm is
	// defense in depth.
	//
	// Reuses the χ² survival helper backing TEST_CHISQ and the
	// MATRIX-host CHISQ family (chiSquareSurvival in
	// internal/processing/test_stat.go) so the overlay and the row-test surface
	// produce identical p-values for the same contingency.
	//
	// Streaming finalize hook: the handler runs at the FacetSchema
	// post-host-finalize entry — once the per-value `(value, count)` map
	// is folded into the FacetField.Discrete.Values slice the overlay
	// reads the already-finalized host distribution + the resolver's
	// population view to emit the SCALAR statistic. The handler depends
	// only on POST-FINALIZE state so running it against a streaming
	// Facet host vs a buffered one produces byte-identical output.
	//
	// Inferential — ALWAYS BUFFERED (per PRD §2 Non-Goals "Streaming
	// overlay path for inferential kinds"). The streamability row is
	// `false` regardless of host streamability — inferential overlays as
	// a family stay buffered until a streamable-test path is plumbed.
	// Distinct from the streamable INDEX_VS_POP / ZSCORE_VS_POP siblings
	// which emit per-value descriptive statistics.
	//
	// Absent-population path: when a host value is missing from the
	// population's discrete payload, pop_freq = 0 and expected = 0.
	// Goodness-of-fit math drops the term (mirrors TEST_CHISQ's "expected
	// > 0" guard) but the low-expected warning still fires.
	//
	// Low-expected-cell warning: when any expected count is below 5 the
	// handler emits ONE PULSE_OVERLAY_EXPECTED_LOW warning carrying the
	// count of low-expected categories and the offending minimum.
	// Canonical errors.PULSE_OVERLAY_EXPECTED_LOW constant — the same
	// warning shape the MATRIX-host CHISQ family + FISHER_EXACT_CELL
	// use (PRD FR-J1 — the warning code is shared with the crosstab
	// Fisher exact path).
	//
	// Degenerate inputs:
	//   - Empty host distribution (no values): the layer emits a SCALAR
	//     payload with NaN statistic + NaN p-value and a layer-level
	//     warning carrying PULSE_OVERLAY_REF_ZERO. No χ² test can be
	//     computed without observed counts.
	//   - subset_N == 0 (every observed count is zero): same as above —
	//     PULSE_OVERLAY_REF_ZERO + NaN statistic.
	//   - pop_freq[v] == 0 for every host value (population is empty):
	//     every expected count is zero, every term drops, statistic
	//     stays at 0 and df = 0. The handler emits NaN statistic + NaN
	//     p-value with PULSE_OVERLAY_REF_ZERO.
	//   - Single category (df = 0): chi-square is undefined; the handler
	//     emits NaN p-value alongside the statistic — descriptive only.
	//
	// Ref handling: `Ref.Population` MUST be populated (the cohort name
	// lives on `Ref.Population.Cohort`); any other ref-family pointer
	// (Margin / Sibling / BaselineIndex / Prior / RollingMean / YoY /
	// Stage / Slot) fires PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE at
	// predict time (per-kind validator lives in internal/descriptor/overlay_facet.go). Mirrors
	// the INDEX_VS_POP / ZSCORE_VS_POP sibling-kind ref contract.
	//
	// Scope must be GROUP. `Level` / `Within` MUST be zero (population
	// comparison is a single-value lookup, not an axis prefix); non-zero
	// values fire PULSE_OVERLAY_LEVEL_OUT_OF_RANGE mirroring the
	// implicit-ref family.
	//
	// Renderer-facing shape: the viz developer reads `OverlayPayload.Scalar`
	// for the χ² statistic and `OverlaySummary` for the renderer
	// metadata. The recommended rendering is a goodness-of-fit badge
	// near the facet header carrying the (statistic, df, p-value) triple
	// — small p-value flags "the subset distribution diverges from the
	// population". The layer-level Baseline stays unset (inferential
	// overlays do not surface a ratio centerpoint).
	OverlayKindChiSqVsPop OverlayKind = "OVERLAY_CHISQ_VS_POP"

	// OverlayKindDeltaVsMargin emits a per-cell additive delta against
	// the matching axis margin: cell - margin. CELL-scoped over a MATRIX
	// (crosstab) host. Unlike INDEX_VS_MARGIN (a ratio) and the SHARE_OF_*
	// triad (each a ratio scaled to 1.0), DELTA_VS_MARGIN preserves the
	// host cell's units — a $-valued AGG_SUM cell minus a $-valued row
	// margin yields a $-valued deviation in the same currency. There is
	// no division and no Welford recurrence, so the handler never
	// surfaces PULSE_OVERLAY_REF_ZERO. Supports all three axes (row /
	// column / grand) — callers pick the axis explicitly via
	// Ref.Margin.Axis and the handler dispatches the matching margin
	// slot. Inherently buffered because the host crosstab path is always
	// buffered (margins recomputed from raw rows).
	OverlayKindDeltaVsMargin OverlayKind = "OVERLAY_DELTA_VS_MARGIN"

	// OverlayKindFisherExactCell emits a per-cell Fisher's exact two-
	// sided p-value computed against a 2×2 contingency table formed from
	// the host crosstab cell, its row margin, its column margin, and the
	// grand total. CELL-scoped over a MATRIX (crosstab) host. Closes the
	// inferential overlay catalog as the canonical low-count χ²
	// backstop — when any expected count in the 2×2 falls below 5 the
	// χ² approximation becomes unreliable and Fisher's exact is the
	// correct surface to compute the p-value.
	//
	// Per-cell 2×2 contingency (for cell at (rowIdx, colIdx)):
	//
	//	            col=c              col≠c
	//	  row=r     cell               row_margin - cell
	//	  row≠r    col_margin - cell   grand - row_margin - col_margin + cell
	//
	// All four cells of the 2×2 are non-negative because every margin is
	// recomputed by the buffered crosstab orchestrator from the same
	// filter-passing row set the cells were built from — the row total
	// dominates each individual row's cell, the column total dominates
	// each individual column's cell, and the grand total equals the sum
	// of row totals (= sum of column totals).
	//
	// Math: Fisher's exact two-sided p-value sums hypergeometric
	// probabilities P(X = x | row_margin, col_margin, grand_total) for
	// every feasible x in the marginal-constrained range whose log-
	// probability is at most logPObs (the observed table's log-prob).
	// Reuses logHypergeometric (internal/processing/test_fisher.go) so the overlay
	// surface produces identical p-values to TEST_FISHER_EXACT for the
	// same 2×2.
	//
	// Output shape: MATRIX payload mirroring the host's RowKeys /
	// ColumnKeys / headers so renderers can lay the overlay on top of
	// the base matrix with the same header machinery as INDEX_VS_MARGIN.
	// Each present host cell becomes a MatrixCell whose Value is the
	// two-sided p-value as a float64. Missing host cells stay absent on
	// the overlay; cells with a missing row or column margin become
	// absent overlay cells (defense in depth — the buffered crosstab
	// orchestrator already populates margins before the overlay fold,
	// so this branch should not fire in practice).
	//
	// Absent-cell policy: a structurally absent host cell (Present=
	// false) stays absent on the overlay (mirrors the SHARE_OF_* triad
	// and INDEX_VS_MARGIN policy — an absent observation does not
	// invent a 2×2).
	//
	// Ref handling: implicit-margin (empty Ref accepted). Row + column
	// margins are resolved from the buffered crosstab host view's
	// MarginFor(Row/Col, ...) resolver. Explicit Ref-family pointers
	// (Margin / Sibling / BaselineIndex / Population / Stage / Slot)
	// fire PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE at predict time.
	// Mirrors the CHISQ_MATRIX / CHISQ_ROW / CHISQ_COL ref policy.
	//
	// Low expected-cell warning (Cochran rule): when ANY of the four
	// 2×2 expected counts {row_margin × col_margin / grand,
	// row_margin × (grand - col_margin) / grand,
	// (grand - row_margin) × col_margin / grand,
	// (grand - row_margin) × (grand - col_margin) / grand} is below 1,
	// OR when at least 20% of the four expected counts are below 5,
	// the handler emits one PULSE_OVERLAY_EXPECTED_LOW warning per
	// offending cell. Canonical errors.PULSE_OVERLAY_EXPECTED_LOW
	// constant. The warning is
	// advisory — Fisher's exact stays exact in the low-count regime and
	// the p-value is still emitted alongside.
	// The threshold runs on the OVERLAY itself (not the underlying χ²
	// surface) because Fisher's exact is the SOLUTION to the low-
	// expected-count problem — the warning's intent here is to flag the
	// CELLS where Fisher's exact (rather than the cheaper χ²
	// approximation) is structurally required.
	//
	// Degenerate inputs:
	//   - grand_total <= 0: layer emits absent cells everywhere
	//     (no 2×2 can be formed); single PULSE_OVERLAY_REF_ZERO warning
	//     surfaces the degenerate host.
	//   - row_margin <= 0 OR col_margin <= 0 OR row_margin >= grand
	//     OR col_margin >= grand for some cell: the 2×2 collapses to a
	//     degenerate shape (one of the four cells must be zero); the
	//     handler still emits a p-value of 1.0 (no rejection possible
	//     under the fully-degenerate hypergeometric) without a warning.
	//
	// Inherently buffered because the host crosstab path is always
	// buffered (margins recomputed from raw rows). PRD § 4.C FR-C2
	// calls out OVERLAY_FISHER_EXACT_CELL as the canonical low-count
	// contingency overlay closing the inferential family.
	OverlayKindFisherExactCell OverlayKind = "OVERLAY_FISHER_EXACT_CELL"

	// OverlayKindFormula emits a per-cell / per-entry / per-scalar
	// expression-driven projection computed from a caller-supplied
	// formula string evaluated against a per-host-shape variable
	// namespace. The expression syntax + evaluator is `expr-lang/expr`
	// — the same evaluator that backs `ATTR_FORMULA` and
	// `FILTER_EXPRESSION` so embedder `ExprFunctions` registered at
	// `pulse.New` time are reachable from FORMULA expressions with no
	// additional registration (the function surface widens; the
	// variable surface stays fixed per-host-shape).
	//
	// Authoring shape:
	//
	//	{
	//	  "kind":  "OVERLAY_FORMULA",
	//	  "scope": "cell",                                   // matrix host
	//	  "params": { "formula": "(cell - margin_grand) / sd_grand" }
	//	}
	//
	// Per-host-shape variable namespace (resolved in research note
	// `.planning/result-overlay-system/research/formula-namespace.md`
	// § 2 and bound by the per-shape binder):
	//
	//   - MATRIX host (Crosstab): `cell`, `margin_row`, `margin_col`,
	//     `margin_grand`, `sd_row`, `sd_col`, `sd_grand` (+ `ref_cell`
	//     when COMPOSE).
	//   - SERIES host (grouped Process / windowed Process / Facet
	//     discrete): `value`, `total`, `prior` (+ `baseline` opt-in via
	//     `Params["baseline_position"]`, + `ref_value` when COMPOSE).
	//   - SCALAR host (whole-matrix p-values, whole-chain SCALAR
	//     overlays, Compose-scalar): `value` (+ `ref` when COMPOSE).
	//   - Compose hosts add the dotted `slot.<label>.{cell|value}`
	//     namespace tied to `Request.Label`.
	//
	// Evaluator: compile-once / run-many — the handler compiles the
	// formula via `expr.Compile` ONCE per overlay spec (at handler
	// entry) against a prototype env carrying zeroed slots for the
	// per-shape variable namespace, then runs the program via
	// `expr.Run` per cell / entry / scalar with the per-iteration env
	// overwriting the prototype's value slots. Mirrors the
	// `processing.formulaAttribute.Row` compile / run pattern (single
	// allocation per overlay layer; O(1) writes per iteration).
	//
	// Predict-time identifier validation: predict
	// parses the formula via `expr-lang/expr/parser`, walks the AST
	// via `expr-lang/expr/ast` (the same packages
	// `processing.NeededFields` walks for `ATTR_FORMULA`), and rejects
	// every identifier not in the per-host-shape variable table or the
	// embedder `ExprFunctions` function set. Unknown identifiers fire
	// `PULSE_OVERLAY_FORMULA_INVALID_IDENT` carrying the offending
	// identifier + the per-shape variable enumerate-set.
	//
	// Failure modes:
	//
	//   - `PULSE_OVERLAY_FORMULA_PARSE_ERROR` — `expr.Compile` returned
	//     a parse error (syntax error in the formula string). Carries
	//     `{formula, parse_error}` Details. Surfaced at both predict
	//     and runtime — the runtime path defends in case the predict
	//     step was bypassed.
	//   - `PULSE_OVERLAY_FORMULA_TYPE_MISMATCH` — `expr.Run` returned a
	//     value whose type cannot be coerced to float64. The coercion
	//     accepts `float64` / `float32` / `int` / `int64` natively,
	//     widens `bool` to `0.0 / 1.0`, and rejects everything else.
	//     Carries `{returned_type, formula}` Details.
	//   - `PULSE_OVERLAY_FORMULA_INVALID_IDENT` — predict-time AST
	//     walk found an identifier not in the per-host-shape variable
	//     table or the function set. Carries `{ident, host_shape,
	//     available_vars}` Details.
	//
	// Buffered-only at v1 across every host shape — the variable
	// namespace depends on post-fold state (margins / totals / SDs are
	// not available mid-stream). The streamability row in
	// `types/overlay_streamability.go` stays `false` regardless of
	// host streamability. Future work may carve out a streamable
	// variant under a distinct kind constant without re-opening this
	// kind's contract; see research note § 6 for the rationale.
	//
	// Scope / Ref handling: the resolved host shape determines which
	// scope values are accepted (MATRIX hosts accept `cell`; SERIES
	// hosts accept `group`; SCALAR hosts accept `total`). Ref family
	// pointers are NOT required — the `ref_cell` / `ref_value` / `ref`
	// COMPOSE variables source from the slot's reference shape (the
	// per-shape binder resolves them). v1 ships in-Request
	// (`Request.Overlays`) and Compose (`ComposedRequest.Overlays`)
	// FORMULA surfaces only; whole-chain FORMULA is deferred
	// (the `stage.<id>.<var>` namespace is documented in the research
	// note for forward-compat).
	//
	// Embedder extensibility: `pulse.Options.Extensions.ExprFunctions`
	// merges into the FORMULA env. Functions widen the function
	// surface only — they do NOT widen the variable identifier surface.
	// Embedders that need new variables MUST register a custom kind
	// via `pulse.Options.Extensions.OverlayKinds` per the existing
	// extension-points policy (CLAUDE.md "Extension Points → Naming
	// policy"); FORMULA cannot widen its variable namespace from
	// outside.
	//
	// LookupTables are OUT of scope at v1 — `lookup(...)` is NOT
	// registered into the FORMULA env. Embedders who need a
	// lookup-driven overlay register the lookup as a custom
	// `ExprFunctions` entry instead (full control over the function
	// signature and predict treatment).
	OverlayKindFormula OverlayKind = "OVERLAY_FORMULA"

	// OverlayKindDeltaVsBaseline emits a per-point additive delta against a
	// single fixed positional baseline of an ordered SERIES (grouped
	// Process) host: `delta_i = point_value_i - baseline_value` where
	// `baseline_value = host.ValueAt(Ref.BaselineIndex.Position)`. GROUP
	// scope over a SERIES host with SERIES payload — one `SeriesEntry` per
	// host group key in host order, each carrying the delta on
	// `Summary.Statistic`. Absolute-difference sibling of
	// `OVERLAY_INDEX_VS_BASELINE`. Like its sibling it consumes the
	// `Ref.BaselineIndex.Position` arm of the OverlayBaselineIndexRef
	// discriminated union.
	//
	// Math (per host group ordinal `i`):
	//
	//	baseline_value = host.ValueAt(Ref.BaselineIndex.Position)
	//	if present[i]  ⇒ point - baseline
	//	if !present[i] ⇒ absent passthrough (no Statistic)
	//
	// Baseline resolution: the handler resolves the baseline value ONCE
	// up front via `processing.ResolveBaselineIndex(host,
	// Ref.BaselineIndex)`. Negative or out-of-range `Position` values
	// fail at predict time
	// (`descriptor.validateOverlayBaselineIndexPredict`) and at runtime
	// (`processing.ResolveBaselineIndex`) with
	// `PULSE_OVERLAY_REF_UNKNOWN` carrying `{baseline_index,
	// series_length}` Details. The handler propagates the resolver's
	// CodedError verbatim — the runtime resolver's coded shape IS the
	// kind's runtime range-check surface (same contract as the
	// `OVERLAY_INDEX_VS_BASELINE` twin).
	//
	// Baseline-at-self semantics: when the host's first present point IS
	// at `Position` (typical "anchor against first point" authoring), that
	// ordinal's delta is exactly `0.0` (self-vs-self under additive
	// subtraction). Renderers centre diverging colour ramps on
	// `baseline = 0` (mirrors `OVERLAY_DELTA_VS_MARGIN` /
	// `OVERLAY_DELTA_VS_SIBLING` / `OVERLAY_ZSCORE_VS_*`).
	//
	// Zero-baseline semantics: unlike the `OVERLAY_INDEX_VS_BASELINE` twin
	// (which divides by the baseline and rejects zero with
	// `PULSE_OVERLAY_REF_ZERO`), DELTA_VS_BASELINE performs subtraction
	// and is mathematically defined for every finite baseline value
	// including zero. The handler does NOT emit
	// `PULSE_OVERLAY_REF_ZERO`; a zero baseline simply yields
	// `delta_i = point_value_i - 0 = point_value_i` (the raw host value
	// passes through). Mirrors the existing `OVERLAY_DELTA_VS_SIBLING`
	// rule against zero sibling values.
	//
	// Absent-point policy: a host that did not produce a value for group
	// `i` (the resolver returns `(0, false)`) surfaces a `SeriesEntry`
	// whose `Summary` leaves `Statistic` unset — the canonical "present
	// slot, empty summary" shape from the SERIES dispatch contract.
	// Absent groups do NOT participate in the delta computation. The
	// baseline ordinal itself MAY be absent — `ResolveBaselineIndex` calls
	// `host.ValueAt` and the host's own resolver decides whether the
	// requested ordinal surfaces a present value or reports absent. An
	// absent baseline (`present=false` at the baseline ordinal) yields a
	// baseline value of `0.0` from the host; subsequent points subtract
	// that zero and the layer carries the raw host values verbatim (no
	// warning — distinct from the `OVERLAY_INDEX_VS_BASELINE` zero-
	// baseline `PULSE_OVERLAY_REF_ZERO` arm).
	//
	// Ref handling: `Ref.BaselineIndex` (with `Position >= 0`) is
	// REQUIRED. Empty `Ref` is rejected at predict time
	// (`PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE`). Any other ref-family
	// pointer (`Margin` / `Sibling` / `Prior` / `Population` / `Stage` /
	// `Slot`) is rejected with the same code.
	//
	// Scope must be GROUP. `Level` / `Within` MUST be zero (the baseline
	// is a single fixed positional anchor, not an axis prefix; non-zero
	// values fire `PULSE_OVERLAY_LEVEL_OUT_OF_RANGE` mirroring the
	// `INDEX_VS_BASELINE` / `INDEX_VS_TOTAL` / `INDEX_VS_PRIOR`
	// implicit-margin / windowed family rule).
	//
	// Buffered. Per `types/overlay_streamability.go`, the streamability
	// row is `false` — resolving a single positional baseline requires
	// the materialised host series (`host.ValueAt(Position)` reads after
	// finalize). The handler runs at the buffered post-host-finalize exit
	// via `ApplyOverlaysSeries`. Forward-compat: future work may lift
	// the baseline resolver into a streaming-aware shape; when that lands
	// the streamability flag flips to true.
	OverlayKindDeltaVsBaseline OverlayKind = "OVERLAY_DELTA_VS_BASELINE"

	// OverlayKindDeltaVsPrior emits a per-point windowed additive delta
	// against the immediately preceding point of an ordered SERIES
	// (grouped Process) host: `delta_i = point_value_i -
	// prior_value_{i-1}`. GROUP scope over a SERIES host with SERIES
	// payload — one `SeriesEntry` per host group key in host order, each
	// carrying the delta on `Summary.Statistic`.
	//
	// Absolute-difference twin of `OVERLAY_INDEX_VS_PRIOR`, standing to
	// it exactly as `OVERLAY_DELTA_VS_BASELINE` stands to
	// `OVERLAY_INDEX_VS_BASELINE`: same host shape, same `Ref.Prior` arm,
	// same single-state lag carrier, subtraction where the index
	// divides. It answers "how much did this change" where the index
	// answers "what proportion of the prior is this" — the two are not
	// interchangeable in a report, which is why both exist.
	//
	// The first present point emits NaN: no prior exists to compare
	// against, and a delta of zero would CLAIM that nothing changed
	// about a comparison that was never made.
	//
	// ⚠ NEVER RAISES `PULSE_OVERLAY_REF_ZERO`, unlike its index twin. A
	// prior of exactly zero is a valid subtrahend — `value - 0` is
	// `value` — so the degenerate-denominator branch that kind needs has
	// no counterpart here. Its absence is deliberate.
	//
	// Streamable. Per `types/overlay_streamability.go`, the streamability
	// row is `true` — the single-state lag carrier is one f64 carried
	// alongside the per-group accumulators inside the streaming Process
	// fold, and the subtract step happens at host finalize. Renderers
	// centre diverging colour ramps on `baseline = 0` (mirrors
	// `OVERLAY_DELTA_VS_BASELINE` / `OVERLAY_DELTA_VS_MARGIN`), NOT on
	// the index family's 100.
	OverlayKindDeltaVsPrior OverlayKind = "OVERLAY_DELTA_VS_PRIOR"

	// OverlayKindDeltaVsSibling emits a per-group additive delta against a
	// sibling group named in `Ref.Sibling`. GROUP scope over a SERIES
	// (grouped Process) host with SERIES payload — one SeriesEntry per
	// host group key in host order, each carrying `group_val - sibling_val`
	// on `Summary.Statistic`. The sibling is identified by `(Field, Value)`
	// — `Field` names a grouper Field present on the SERIES host, `Value`
	// names the specific axis-key value to compare against. The sibling
	// reference resolves to a single host group via the sibling resolver
	// (`internal/processing/overlay_sibling_resolver.go`); every present group
	// emits a delta against that fixed reference point. The sibling
	// group itself emits `0` (self-vs-self under additive subtraction).
	//
	// Buffered (per kind-catalog-v1 "Streaming-capable subset"): sibling
	// resolution requires the full materialised SeriesPayload — the
	// streaming Process pass cannot resolve a `(Field, Value)` lookup
	// against the per-group accumulators until they are finalised, so the
	// handler runs at the buffered post-host-finalize exit. The
	// `OverlayStreamability[OverlayKindDeltaVsSibling]` row is `false`
	// (mirrors `OverlayKindIndexVsSibling`).
	//
	// Math (per host group i):
	//
	//	sibling_val = host[Ref.Sibling.Field, Ref.Sibling.Value]   // resolver lookup
	//	delta_i     = group_val[i] - sibling_val
	//
	// Absent-group policy: a host that did not produce a value for group
	// i (resolver returns `(0, false)`) surfaces a SeriesEntry whose
	// Summary leaves Statistic unset — canonical "present slot, empty
	// summary" shape from the SERIES dispatch contract. Absent groups
	// do NOT participate in the delta computation (and DO NOT surface
	// zero — they carry no Statistic).
	//
	// Unknown sibling path: when `Ref.Sibling.Field` is not a grouper
	// field on the host OR `Ref.Sibling.Value` does not match any
	// observed axis-key value, the handler emits ONE
	// PULSE_OVERLAY_REF_UNKNOWN warning carrying the offending
	// `(field, value)` pair and surfaces NaN statistics across every
	// present entry. Mirrors the INDEX_VS_TOTAL / SHARE_OF_TOTAL SERIES
	// PULSE_OVERLAY_REF_ZERO emission shape (one warning per layer, not
	// per cell). DELTA is mathematically defined even when sibling is
	// resolved AND sibling_val is zero — the delta is simply
	// `group_val[i] - 0 = group_val[i]`, so the zero-sibling-value case
	// does NOT raise PULSE_OVERLAY_REF_ZERO on this kind (unlike the
	// INDEX_VS_SIBLING twin which divides by sibling and rejects zero).
	//
	// Ref handling: `Ref.Sibling` is REQUIRED — both `Field` and `Value`
	// must be non-empty strings. Any other ref-family pointer (Margin /
	// BaselineIndex / Population / Stage / Slot) fails
	// PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE at predict time.
	//
	// Scope must be GROUP. The validator rejects any other scope.
	OverlayKindDeltaVsSibling OverlayKind = "OVERLAY_DELTA_VS_SIBLING"

	// OverlayKindIndexVsBaseline emits a per-point ratio index against a
	// single fixed positional baseline of an ordered SERIES (grouped
	// Process) host: `index_i = point_value_i / baseline_value * 100`
	// where `baseline_value` is the host's metric at the ordinal pinned
	// by `Ref.BaselineIndex.Position`. GROUP scope over a SERIES host with
	// SERIES payload — one `SeriesEntry` per host group key in host order,
	// each carrying the index on `Summary.Statistic`. Second windowed-
	// Process overlay in the catalog (first kind to consume the
	// `Ref.BaselineIndex.Position` arm of the OverlayBaselineIndexRef
	// discriminated union; sibling to `OVERLAY_INDEX_VS_PRIOR`).
	//
	// Math (per host group ordinal `i`):
	//
	//	baseline_value = host.ValueAt(Ref.BaselineIndex.Position)
	//	if baseline_value == 0 ⇒ NaN + warning  (PULSE_OVERLAY_REF_ZERO)
	//	if present[i]          ⇒ point / baseline * 100
	//	if !present[i]         ⇒ absent passthrough (no Statistic)
	//
	// Baseline resolution: the handler resolves the baseline value ONCE
	// up front via `processing.ResolveBaselineIndex(host,
	// Ref.BaselineIndex)`. Negative or out-of-range `Position` values
	// fail at predict time
	// (`descriptor.validateOverlayBaselineIndexPredict`) and at runtime
	// (`processing.ResolveBaselineIndex`) with
	// `PULSE_OVERLAY_REF_UNKNOWN` carrying `{baseline_index,
	// series_length}` Details. The handler propagates the resolver's
	// CodedError verbatim — the runtime resolver's coded shape IS the
	// kind's runtime range-check surface.
	//
	// Baseline-at-self semantics: when the host's first present point is
	// at `Position` (typical "anchor against first point" authoring), that
	// ordinal's index is exactly `100.0` (self-vs-self under the ratio
	// scaling). Renderers centre diverging colour ramps on `baseline = 100`
	// (mirrors `OVERLAY_INDEX_VS_MARGIN` / `OVERLAY_INDEX_VS_TOTAL` /
	// `OVERLAY_INDEX_VS_SIBLING` / `OVERLAY_INDEX_VS_PRIOR`).
	//
	// Zero-baseline path: when the resolved baseline value is `0` the
	// handler emits ONE `PULSE_OVERLAY_REF_ZERO` warning carrying the
	// overlay kind, the host group count, and the baseline ordinal; every
	// emitted entry's `Summary.Statistic` is NaN. Division by zero is
	// mathematically undefined and the same `PULSE_OVERLAY_REF_ZERO`
	// contract used by the share / index / zscore family applies (one
	// warning per layer, not per cell). Distinct from the
	// `OVERLAY_DELTA_VS_BASELINE` twin which performs subtraction and
	// does NOT raise on zero baseline.
	//
	// Absent-point policy: a host that did not produce a value for group
	// `i` (the resolver returns `(0, false)`) surfaces a `SeriesEntry`
	// whose `Summary` leaves `Statistic` unset — the canonical "present
	// slot, empty summary" shape from the SERIES dispatch contract.
	// Absent groups do NOT participate in the index computation. The
	// baseline ordinal itself MAY be absent — `ResolveBaselineIndex` calls
	// `host.ValueAt` and the host's own resolver decides whether the
	// requested ordinal surfaces a present value or reports absent. An
	// absent baseline (`present=false` at the baseline ordinal) yields a
	// baseline value of `0.0` from the host, which then routes through
	// the zero-baseline `PULSE_OVERLAY_REF_ZERO` arm above.
	//
	// Ref handling: `Ref.BaselineIndex` (with `Position >= 0`) is REQUIRED.
	// Empty `Ref` is rejected at predict time
	// (`PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE`). Any other ref-family
	// pointer (`Margin` / `Sibling` / `Prior` / `Population` / `Stage` /
	// `Slot`) is rejected with the same code.
	//
	// Scope must be GROUP. `Level` / `Within` MUST be zero (the baseline
	// is a single fixed positional anchor, not an axis prefix; non-zero
	// values fire `PULSE_OVERLAY_LEVEL_OUT_OF_RANGE` mirroring the
	// `INDEX_VS_TOTAL` / `INDEX_VS_PRIOR` implicit-margin / windowed
	// family rule).
	//
	// Buffered. Per `types/overlay_streamability.go`, the streamability
	// row is `false` — resolving a single positional baseline requires
	// the materialised host series (`host.ValueAt(Position)` reads after
	// finalize). The handler runs at the buffered post-host-finalize exit
	// via `ApplyOverlaysSeries`. Forward-compat: future work may lift
	// the baseline resolver into a streaming-aware shape (carrying the
	// resolved baseline inline as a kind-specific accumulator advanced
	// during the streaming pass once the orchestrator hits the baseline
	// ordinal); when that lands the streamability flag flips to true.
	OverlayKindIndexVsBaseline OverlayKind = "OVERLAY_INDEX_VS_BASELINE"

	// OverlayKindIndexVsMargin produces an index score per cell (or per
	// row/column, depending on Scope) by comparing the cell value against
	// the matching axis margin: 100 * cell / margin. Scope=CELL emits one
	// scalar per cell; Scope=ROW or COLUMN emits one scalar per axis key
	// when the comparison degenerates (e.g. row-share index vs grand
	// total). The default reference (Ref.Margin) names the axis whose
	// margin is the denominator. Inherently buffered because margins are
	// always recomputed from raw rows in the crosstab path.
	OverlayKindIndexVsMargin OverlayKind = "OVERLAY_INDEX_VS_MARGIN"

	// OverlayKindIndexVsPop emits a per-value population-comparison index
	// against a Facet host. For each value of the host Facet field the layer
	// surfaces `subset_freq / pop_freq * 100` where `subset_freq` is the
	// host FacetResult's per-value frequency (one filtered cohort) and
	// `pop_freq` is the resolver-supplied per-value frequency of the
	// reference population (typically an unfiltered or alternately-filtered
	// cohort). GROUP scope over a FACET host with SERIES payload — one
	// `SeriesEntry` per host value in payload order, each carrying the
	// index on `Summary.Statistic`. First FACET-host overlay in the
	// catalog and the first kind to consume the
	// `Ref.Population` arm of the OverlayRef discriminated union (the
	// resolver shape lives at `processing.FacetPopulationView`).
	//
	// Math (per host value `v`):
	//
	//	subset_freq = host.Discrete.Values[v].Count / host.FilteredRecords
	//	pop_freq    = population.DiscreteFrequency(v)
	//	if pop_freq == 0 ⇒ NaN entry + PULSE_OVERLAY_REF_ZERO (skip)
	//	otherwise        ⇒ subset_freq / pop_freq * 100
	//
	// Streaming finalize hook: the handler runs at
	// the FacetSchema streaming finalize point — once the per-value
	// `(value, count)` map is folded into the `FacetField.Discrete.Values`
	// slice the overlay reads the already-finalized host distribution and
	// the resolver's population view to emit the per-value index. No
	// second pass over records. The streaming-vs-buffered byte-identity
	// guarantee for the host Facet path holds because the handler depends
	// ONLY on POST-FINALIZE state.
	//
	// Categorical host fast path (v1 scope): the handler walks the
	// host's `FacetDiscrete.Values` slice in payload order (descending by
	// count, ties ascending by value-string) and the resolver looks each
	// value up in the population's discrete payload via
	// `FacetPopulationView.DiscreteFrequency(value)`. One division per
	// host value.
	//
	// Numeric host path (v1 scope): the handler walks the host's
	// histogram bins (when `IncludeHistogram` was true on the host
	// FacetRequest) and emits one index per bin via the resolver's
	// `NumericHistogram()` surface — same `subset_bin_freq /
	// pop_bin_freq * 100` math. When the host did not request a
	// histogram the kind emits zero entries (the host shape carries
	// only Welford summary stats, not per-value tallies — without a
	// histogram there are no per-value buckets to index). The handler
	// does NOT walk percentiles — percentile-bucket indexing is reserved
	// for `OVERLAY_KS_VS_POP`.
	//
	// Zero pop_freq path: when `pop_freq == 0` for some value v (the
	// value never appeared in the population, or the population has zero
	// records altogether), the handler emits ONE
	// `PULSE_OVERLAY_REF_ZERO` warning per affected entry carrying the
	// kind + value and SKIPS the index entry (Statistic stays unset on
	// that entry). The acceptance criterion is explicit: "on
	// `pop_freq == 0` emit warning code `PULSE_OVERLAY_REF_ZERO` and
	// skip the index entry". Subsequent entries continue to emit indices
	// against the same population view.
	//
	// Absent-population path: when the resolver could not find any
	// population entry for `value` (the value never appeared in the
	// population dictionary), the handler treats it as the zero-pop_freq
	// case and emits the same warning + skip behavior. Distinct from
	// `PULSE_OVERLAY_REF_UNKNOWN` which fires at the predict / runtime
	// boundary when the named population FIELD is unknown (the resolver
	// itself returns that code from `ResolveFacetPopulation`).
	//
	// Ref handling: `Ref.Population` MUST be populated. The Population
	// arm carries the comparison-population cohort name (resolver
	// matches against a FacetResult derived from that cohort). Any other
	// ref-family pointer (`Margin` / `Sibling` / `BaselineIndex` /
	// `Prior` / `RollingMean` / `YoY` / `Stage` / `Slot`) fires
	// `PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE` at predict time (the
	// per-kind validator lives in internal/descriptor/overlay_facet.go).
	//
	// Scope must be GROUP. `Level` / `Within` MUST be zero (population
	// comparison is a single-value lookup, not an axis prefix); non-zero
	// values fire `PULSE_OVERLAY_LEVEL_OUT_OF_RANGE` mirroring the other
	// implicit-ref kinds.
	//
	// Streamable. Per `types/overlay_streamability.go`, the streamability
	// row is `true` — the handler runs as a single post-finalize fold
	// over the host's already-materialized per-value distribution and
	// the resolver's already-materialized population view. The
	// host-side streaming Facet pass keeps its existing online
	// accumulators (Welford / per-value count map); the overlay does
	// NOT widen the streaming carrier — it consumes finalized state.
	// Streamable matches the kind-catalog-v1 "Streaming-capable subset"
	// — `OVERLAY_INDEX_VS_POP` is explicitly listed as YES.
	//
	// Renderers centre diverging colour ramps on `baseline = 100`
	// (mirrors `OVERLAY_INDEX_VS_MARGIN` / `OVERLAY_INDEX_VS_TOTAL` /
	// `OVERLAY_INDEX_VS_SIBLING` / `OVERLAY_INDEX_VS_PRIOR` /
	// `OVERLAY_INDEX_VS_BASELINE`). Per-entry Statistic carries the
	// renderer-facing index value; layer-level Summary carries the
	// baseline + Min/Max/Count summary over present entries.
	OverlayKindIndexVsPop OverlayKind = "OVERLAY_INDEX_VS_POP"

	// OverlayKindIndexVsPrior emits a per-point windowed index against the
	// immediately preceding point of an ordered SERIES (grouped Process)
	// host: `index_i = point_value_i / prior_value_{i-1} * 100`. GROUP
	// scope over a SERIES host with SERIES payload — one `SeriesEntry`
	// per host group key in host order, each carrying the index on
	// `Summary.Statistic`. First **streamable** windowed-Process overlay
	// in the catalog and the first kind to use the windowed
	// `Ref.Prior` arm of the `OverlayRef` discriminated union.
	//
	// Math (per host group ordinal `i`):
	//
	//	if i == 0           ⇒ NaN              (no prior available)
	//	if prior_value == 0 ⇒ NaN + warning    (PULSE_OVERLAY_REF_ZERO)
	//	otherwise           ⇒ point / prior * 100
	//
	// Carrier shape (single-state lag): the handler walks the ordered
	// host series once. A single `float64` lag carrier remembers the most
	// recently seen PRESENT value; each subsequent present point divides
	// by the carrier and then advances the carrier to its own value.
	// Absent host points (resolver reports `(0, false)`) emit NaN for
	// that ordinal and DO NOT advance the carrier — the "prior" for the
	// next present point remains the last present value. This single-
	// state lag is what makes the kind streamable: the streaming-Process
	// orchestrator carries one f64 lag value alongside the per-group
	// accumulators inside the streaming fold, and the post-host finalize
	// is the divide step.
	//
	// First-point semantics: the first ordinal has no prior by
	// construction. The handler emits NaN on the first present entry and
	// does NOT raise `PULSE_OVERLAY_REF_ZERO` — this is "no comparison
	// available" rather than "denominator was zero". Renderers should
	// surface the first entry as "no comparison" (typically a blank
	// cell) rather than a degenerate signal.
	//
	// Zero-prior path: when the lag carrier is `0` at the divide step
	// (the previous present point had a value of zero), the handler emits
	// one `PULSE_OVERLAY_REF_ZERO` warning and surfaces NaN on the
	// affected entries. Subsequent points continue to use the same lag
	// carrier (since absent points do not advance the carrier, but a
	// PRESENT zero DOES advance the carrier — and the next point will
	// then again hit the zero-prior path). Mirrors the existing
	// `PULSE_OVERLAY_REF_ZERO` contract used by the share / index /
	// zscore family.
	//
	// Forward-compat lag knob: the `Ref.Prior.Lag` slot is reserved for
	// future window-N priors (e.g. lag-3 for "compare against three
	// points ago"). v1 ships lag-1 only — non-zero `Lag` is not
	// exercised by this kind today; later stories will widen the carrier
	// to a small ring buffer.
	//
	// Ref handling: the windowed `Ref.Prior` arm is the implicit default
	// for this kind. The validator accepts both a populated
	// `Ref.Prior` (with `Lag` zero or unset for v1) AND an entirely empty
	// `Ref` (the omitempty-friendly authoring shape) — both spell "lag-
	// 1 prior". Any other ref-family pointer (`Margin` / `Sibling` /
	// `BaselineIndex` / `Population` / `Stage` / `Slot`) fires
	// `PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE` at predict time.
	//
	// Scope must be GROUP. `Level` / `Within` MUST be zero (windowed
	// kind — the lag carrier folds across the ordered axis without a
	// prefix-bucket denominator; non-zero values fire
	// `PULSE_OVERLAY_LEVEL_OUT_OF_RANGE` mirroring the
	// `INDEX_VS_TOTAL` / χ² / Fisher implicit-margin family).
	//
	// Streamable. Per `types/overlay_streamability.go`, the streamability
	// row is `true` — the single-state lag carrier is one f64 carried
	// alongside the per-group accumulators inside the streaming Process
	// fold, and the divide step happens at host finalize. Renderers
	// centre diverging colour ramps on `baseline = 100` (mirrors
	// `OVERLAY_INDEX_VS_MARGIN` / `OVERLAY_INDEX_VS_TOTAL`).
	OverlayKindIndexVsPrior OverlayKind = "OVERLAY_INDEX_VS_PRIOR"

	// OverlayKindIndexVsRollingMean emits a per-point windowed index against
	// the arithmetic mean of the W immediately preceding points of an ordered
	// SERIES (grouped Process) host: `index_i = point_value_i / mean(point_{i-W} .. point_{i-1}) * 100`.
	// GROUP scope over a SERIES host with SERIES payload — one `SeriesEntry`
	// per host group key in host order, each carrying the index on
	// `Summary.Statistic`. Fourth windowed-Process overlay in the catalog
	// (siblings: `OVERLAY_INDEX_VS_PRIOR`, `OVERLAY_INDEX_VS_BASELINE`,
	// `OVERLAY_DELTA_VS_BASELINE`) and the first kind to consume the
	// `Ref.RollingMean` arm of the OverlayRef discriminated union.
	//
	// Window-via-Params convention: the rolling window width is supplied via
	// `OverlaySpec.Params["window"]` as a positive integer (mirrors the
	// `WIN_*` operator convention; see `skills/window-design.md` for the
	// pattern). The `Ref.RollingMean` arm is an empty marker struct
	// (`OverlayRollingMeanRef{}`) tagging the ref family — the v1 window
	// value lives entirely on `Params`. Forward-compat: `OverlayRollingMeanRef`
	// may grow non-Window knobs (e.g. weighting modes) without re-opening
	// the parent `OverlayRef`.
	//
	// Math (per host group ordinal `i`):
	//
	//	W = Params["window"] (positive int)
	//	if fewer than W present prior points have been seen ⇒ NaN (no warning)
	//	if mean(prior W points) == 0                       ⇒ NaN + PULSE_OVERLAY_REF_ZERO
	//	otherwise                                          ⇒ point / mean * 100
	//
	// Carrier shape (rolling window, buffered): the handler maintains a ring
	// buffer of the W most recently observed PRESENT values. The stored
	// shape is the (count, mean, M2) Welford triple — only the mean
	// is read by INDEX_VS_ROLLING_MEAN, but the M2 slot is reserved so the
	// `OVERLAY_ZSCORE_VS_ROLLING` handler can lift `sqrt(M2 / (count-1))`
	// from the same carrier (the per-group accumulator cost is +1 f64 per
	// layer per group — trivial relative to the overlay grand-budget; the
	// reuse keeps the windowed family's accumulator footprint flat as more
	// kinds land).
	//
	// Absent-point policy (ring buffer does not advance): an absent host
	// ordinal (resolver reports `(0, false)`) emits a present `SeriesEntry`
	// whose Summary leaves Statistic unset and DOES NOT advance the ring
	// buffer. Mirrors the `OVERLAY_INDEX_VS_PRIOR` absent-point lag carrier
	// rule — the next present ordinal will compare against the most recent
	// W PRESENT values, not absent slots.
	//
	// Window-fill semantics: the first W present ordinals all emit NaN
	// without warning — "window not yet filled" is structurally distinct
	// from "denominator was zero" (mirrors the `OVERLAY_INDEX_VS_PRIOR`
	// first-point NaN rule). When the host series is shorter than W (no
	// ordinal ever sees a full window) every entry's Statistic is NaN with
	// no warning.
	//
	// Zero-rolling-mean path: when the window mean is exactly `0` at the
	// divide step (e.g. every prior point in the window was zero) the
	// handler emits ONE `PULSE_OVERLAY_REF_ZERO` warning and surfaces NaN
	// on the affected entry. Subsequent points may again hit the zero-mean
	// path as the ring rolls; one warning per layer per zero-mean event
	// occurrence. Mirrors the share / index / zscore family's
	// zero-denominator contract.
	//
	// Window param validation: `Params["window"]` MUST be present and
	// MUST be a positive integer (JSON numbers decoded as float64 are
	// accepted when integral). Missing param fires
	// `PULSE_OVERLAY_PARAM_MISSING` carrying `{kind, param}` Details at
	// both predict (`descriptor.validateOverlayIndexVsRollingMean`) and
	// runtime (`processing.applyIndexVsRollingMean`). Window `<= 0` fires
	// `PULSE_OVERLAY_LEVEL_OUT_OF_RANGE` carrying `{window}` Details — the
	// LEVEL_OUT_OF_RANGE code is reused for "value out of valid range"
	// semantics so the new code surface stays narrow (mirrors the existing
	// usage on Level / Within slots).
	//
	// Ref handling: `Ref.RollingMean` MUST be populated (empty struct is
	// fine; the marker tags the ref family). Any other ref-family pointer
	// (`Margin` / `Sibling` / `BaselineIndex` / `Prior` / `Population` /
	// `Stage` / `Slot`) fires `PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE`
	// at predict time.
	//
	// Scope must be GROUP. `Level` / `Within` MUST be zero (windowed kind —
	// the rolling-mean carrier folds across the ordered axis without a
	// prefix-bucket denominator; non-zero values fire
	// `PULSE_OVERLAY_LEVEL_OUT_OF_RANGE` mirroring the
	// `INDEX_VS_PRIOR` / `INDEX_VS_BASELINE` / `INDEX_VS_TOTAL`
	// implicit-margin / windowed family).
	//
	// Buffered. Per `types/overlay_streamability.go`, the streamability row
	// is `false` — the ring buffer carries the full window of present values
	// per group, which the streaming Process pass cannot maintain inline
	// with the per-record fold today (the carrier widens beyond a single
	// f64 — `OVERLAY_INDEX_VS_PRIOR`'s streamable lag carrier is one f64;
	// rolling-mean's ring is `W` f64s and grows the streaming-fold state
	// past v1's single-state lag accumulator). Forward-compat: a future
	// story may lift the rolling-mean ring into a streaming-aware shape
	// (the streaming orchestrator's per-group accumulator carries the ring
	// inline alongside the per-group online aggregator); when that lands
	// the streamability flag flips to true.
	OverlayKindIndexVsRollingMean OverlayKind = "OVERLAY_INDEX_VS_ROLLING_MEAN"

	// OverlayKindIndexVsStage is the whole-chain ratio overlay against
	// another ProcessChain stage's result. CHAIN scope over a CHAIN
	// (ProcessChain) host with a shape inherited from the target stage
	// (scalar / series / matrix depending on the target stage's host
	// result shape). The first whole-chain overlay in the catalog
	// (whole-chain kind; runtime handler in internal/processing/) and the
	// first kind to consume the StageRef discriminated reference family
	// (Ref + Target slots on `ChainOverlaySpec` — both populate exactly
	// one of Index / Name per StageRef value).
	//
	// Math (per host coordinate `k`):
	//
	//	target_val_k = target_stage.ValueAt(k)
	//	ref_val_k    = ref_stage.ValueAt(k)
	//	if ref_val_k == 0 ⇒ NaN + warning (PULSE_OVERLAY_REF_ZERO)
	//	otherwise         ⇒ target_val_k / ref_val_k * 100
	//
	// Whole-chain barrier semantics: the handler runs at the
	// post-stage-loop barrier inside `internal/service.ProcessChain` (see
	// `internal/service/chain.go`'s `applyChainOverlays` hook). Per-stage overlays
	// (`Stages[i].Overlays` on the request half of the dual-slot design)
	// land on each stage's individual `Response.Overlays` as a side
	// effect of the per-stage Process call; whole-chain overlays land on
	// `ChainResponse.Overlays` AFTER every stage has finalised. The
	// whole-chain fold operates exclusively on already-materialised
	// `*Response` objects — no record re-traversal.
	//
	// Default Target: when both `Target.Index` is nil AND `Target.Name`
	// is empty, the resolver defaults to the latest stage
	// (`len(Stages) - 1`). The default makes the typical "anchor against
	// the chain's final result" authoring shape concise. Setting either
	// slot explicitly overrides the default. `Ref` has no default —
	// every spec MUST name a baseline stage explicitly.
	//
	// Shape-divergence rule (PRD §6 FR-F2): when the target stage's host
	// shape (matrix vs series vs scalar) differs from the reference
	// stage's host shape the divergence is a
	// `PULSE_OVERLAY_CHAIN_STAGE_SHAPE_DIVERGENT` WARNING on predict-chain
	// and at runtime alike (shapes read off the authored stage
	// requests): the chain runs and the layer is an empty payload in the
	// target stage's shape.
	//
	// Unknown stage path: when `Target` or `Ref` names a stage that does
	// not exist (Index out of range OR Name does not match any
	// `ChainStage.Name`), the resolver fires
	// `PULSE_OVERLAY_TARGET_UNKNOWN` / `PULSE_OVERLAY_REFERENCE_UNKNOWN`
	// respectively (catalog reservations — until those codes land, the
	// dispatcher chassis falls back to `PULSE_OVERLAY_REF_UNKNOWN` for
	// both arms).
	//
	// Scope must be CHAIN. `Level` / `Within` MUST be zero (the
	// reference is a single named stage, not an axis prefix); non-zero
	// values fire `PULSE_OVERLAY_LEVEL_OUT_OF_RANGE` mirroring the
	// implicit-ref family.
	//
	// Buffered. Per `types/overlay_streamability.go`, the streamability
	// row is `false` — the whole-chain barrier runs after every stage
	// has produced a `*Response`, so there is no streamable arm for the
	// whole-chain kind family by construction. Renderers centre
	// diverging colour ramps on `baseline = 100` (mirrors the
	// INDEX_VS_* family on other host shapes).
	OverlayKindIndexVsStage OverlayKind = "OVERLAY_INDEX_VS_STAGE"

	// OverlayKindDeltaVsStage is the whole-chain additive-delta sibling
	// of `OVERLAY_INDEX_VS_STAGE`. CHAIN scope over a CHAIN (ProcessChain)
	// host with a shape inherited from the target stage (scalar / series
	// / matrix depending on the target stage's host result shape).
	// Second whole-chain overlay in the catalog (runtime handler in
	// internal/processing/).
	//
	// Math (per host coordinate `k`):
	//
	//	target_val_k = target_stage.ValueAt(k)
	//	ref_val_k    = ref_stage.ValueAt(k)
	//	delta_k      = target_val_k - ref_val_k
	//
	// Unlike the `OVERLAY_INDEX_VS_STAGE` twin (which divides by the
	// reference value and emits `PULSE_OVERLAY_REF_ZERO` against a zero
	// denominator), `OVERLAY_DELTA_VS_STAGE` performs subtraction and is
	// mathematically defined for every finite reference value including
	// zero — the handler does NOT emit `PULSE_OVERLAY_REF_ZERO`. Mirrors
	// the `OVERLAY_DELTA_VS_BASELINE` / `OVERLAY_DELTA_VS_MARGIN` /
	// `OVERLAY_DELTA_VS_SIBLING` family rule.
	//
	// Output preserves the target stage's units — a $-valued aggregator
	// in the target stage minus a $-valued aggregator in the reference
	// stage yields a $-valued deviation in the same currency. Renderers
	// centre diverging colour ramps on `baseline = 0` (mirrors the rest
	// of the DELTA family on other host shapes).
	//
	// Shape-divergence rule (PRD §6 FR-F2): same as
	// `OVERLAY_INDEX_VS_STAGE` — when the target stage's host shape
	// differs from the reference stage's host shape the divergence is a
	// `PULSE_OVERLAY_CHAIN_STAGE_SHAPE_DIVERGENT` WARNING on predict-chain
	// and at runtime alike, over an empty layer.
	//
	// Default Target / Unknown-stage / Scope / Level / Within / Buffered
	// rules: identical to `OVERLAY_INDEX_VS_STAGE`.
	OverlayKindDeltaVsStage OverlayKind = "OVERLAY_DELTA_VS_STAGE"

	// OverlayKindIndexVsSibling emits a per-group index score against a
	// sibling group named in `Ref.Sibling`: `(group_val / sibling_val) *
	// 100.0` per host group key. GROUP scope over a SERIES (grouped
	// Process) host with SERIES payload — one SeriesEntry per host group
	// key in host order, each carrying the index on `Summary.Statistic`.
	// The sibling is identified by `(Field, Value)` — `Field` names a
	// grouper Field present on the SERIES host, `Value` names the
	// specific axis-key value to compare against. The sibling reference
	// resolves to a single host group via the sibling resolver
	// (`internal/processing/overlay_sibling_resolver.go`); every present group
	// emits an index against that fixed reference point. The sibling
	// group itself emits `100.0` (self-vs-self under the ratio scaling).
	//
	// Buffered (per kind-catalog-v1 "Streaming-capable subset"): sibling
	// resolution requires the full materialised SeriesPayload — the
	// streaming Process pass cannot resolve a `(Field, Value)` lookup
	// against the per-group accumulators until they are finalised, so the
	// handler runs at the buffered post-host-finalize exit. The
	// `OverlayStreamability[OverlayKindIndexVsSibling]` row is `false`
	// (mirrors `OverlayKindDeltaVsSibling`).
	//
	// Math (per host group i):
	//
	//	sibling_val = host[Ref.Sibling.Field, Ref.Sibling.Value]   // resolver lookup
	//	index_i     = (group_val[i] / sibling_val) * 100.0
	//
	// Absent-group policy: a host that did not produce a value for group
	// i (resolver returns `(0, false)`) surfaces a SeriesEntry whose
	// Summary leaves Statistic unset — canonical "present slot, empty
	// summary" shape from the SERIES dispatch contract. Absent groups
	// do NOT participate in the index computation.
	//
	// Unknown sibling path: when `Ref.Sibling.Field` is not a grouper
	// field on the host OR `Ref.Sibling.Value` does not match any
	// observed axis-key value, the handler emits ONE
	// PULSE_OVERLAY_REF_UNKNOWN warning carrying the offending
	// `(field, value)` pair and surfaces NaN statistics across every
	// present entry. Mirrors DELTA_VS_SIBLING's unknown-sibling
	// emission shape.
	//
	// Zero-sibling path: when the sibling resolves but its value is zero
	// (legitimate group with a zero post-filter sum), the handler emits
	// ONE PULSE_OVERLAY_REF_ZERO warning and surfaces NaN across every
	// present entry — division by zero is mathematically undefined and
	// the same PULSE_OVERLAY_REF_ZERO contract the SERIES INDEX_VS_TOTAL
	// / SHARE_OF_TOTAL kinds use applies here. DELTA_VS_SIBLING does NOT
	// emit this warning (subtraction by zero is well-defined).
	//
	// Ref handling: `Ref.Sibling` is REQUIRED — both `Field` and `Value`
	// must be non-empty strings. Any other ref-family pointer (Margin /
	// BaselineIndex / Population / Stage / Slot) fails
	// PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE at predict time.
	//
	// Scope must be GROUP. The validator rejects any other scope.
	OverlayKindIndexVsSibling OverlayKind = "OVERLAY_INDEX_VS_SIBLING"

	// OverlayKindIndexVsTotal emits a per-group index score against the
	// grand total of a SERIES host (grouped Process result): for each
	// host group key the layer surfaces `(group_val / grand_total) *
	// 100.0`. GROUP scope over a SERIES (grouped Process) host with
	// SERIES payload — one SeriesEntry per host group key in host order,
	// each carrying the index score on `Summary.Statistic`. First
	// streamable overlay in the catalog (per kind-catalog-v1 §
	// "Streaming-capable subset"): the handler folds at the end of the
	// existing streaming Process pass via a running grand-total
	// accumulator that runs alongside the per-group accumulators — no
	// second pass over records, the post-host finalize divides each
	// group value by the running grand total.
	//
	// Math (per host group i):
	//
	//	grand_total = Σ_j group_val[j]   (post-filter rows, AGG_SUM
	//	                                   semantics — never reads pre-
	//	                                   filter row count)
	//	index_i     = (group_val[i] / grand_total) * 100.0
	//
	// Zero-grand-total path: when grand_total == 0 (every group's
	// post-filter value sums to zero, including the degenerate "no
	// groups survived the filter" case) the handler emits ONE
	// PULSE_OVERLAY_REF_ZERO warning and populates every entry's
	// Summary.Statistic with NaN. Mirrors the existing
	// PULSE_OVERLAY_REF_ZERO contract used by the share / index family
	// against a missing axis margin on the MATRIX host.
	//
	// Absent-group policy: a host that did not produce a record for
	// group i (the resolver returns (0, false)) surfaces a SeriesEntry
	// whose Summary leaves Statistic unset — the canonical "present
	// slot, empty summary" shape established by the SERIES
	// dispatch contract. Absent groups do NOT contribute to the grand
	// total (the resolver gates the accumulator the same way it gates
	// per-group emission).
	//
	// Ref handling: implicit-grand-total. The Ref union is left EMPTY
	// — the kind's denominator is the host series' own grand total, so
	// callers supplying any Ref family pointer (Margin / Sibling /
	// BaselineIndex / Population / Stage / Slot) fail
	// PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE at predict time
	// (mirrors the CHISQ_* implicit-margin contract).
	//
	// Scope is GROUP (not CELL or ROW): the kind decorates each grouper
	// level the host emits. The validator rejects any other scope.
	//
	// Streamable. Per types/overlay_streamability.go, the streamability
	// row is `true` — the grand-total accumulator is one f64 carried
	// alongside the per-group accumulators inside the streaming Process
	// fold, and the division step happens at host finalize. The
	// streaming-Process orchestrator wires the inner per-record hook;
	// this kind ships with a SERIES-host post-finalize entry
	// (ApplyOverlaysSeries route) so the streaming-vs-buffered byte-
	// identity test holds at the entry-point level today.
	OverlayKindIndexVsTotal OverlayKind = "OVERLAY_INDEX_VS_TOTAL"

	// OverlayKindKSVsPop emits a single scalar Kolmogorov-Smirnov distance
	// (`D = sup_x |F_subset(x) - F_pop(x)|`) plus an asymptotic p-value
	// comparing the host Facet subset NUMERIC distribution against the
	// resolved population NUMERIC distribution. GROUP scope over a FACET
	// (FacetSchema) host with SCALAR payload — the layer carries the KS
	// statistic plus its asymptotic p-value via OverlaySummary{Statistic,
	// PValue, Parameters{"n_subset", "n_pop"}}. Fourth and final FACET-host
	// overlay in the catalog (siblings: OVERLAY_INDEX_VS_POP
	// descriptive, OVERLAY_ZSCORE_VS_POP descriptive,
	// OVERLAY_CHISQ_VS_POP inferential discrete-arm only). KS is
	// the canonical NUMERIC-arm distributional-shift indicator — it pairs
	// with CHISQ_VS_POP as the two inferential FACET-host kinds: CHISQ
	// quantifies divergence on categorical distributions, KS quantifies
	// divergence on numeric distributions. The viz developer renders the
	// SCALAR statistic as a distributional-shift indicator near the facet
	// header.
	//
	// Math:
	//
	//	D       = sup_x |F_subset(x) - F_pop(x)|      // KS distance
	//	n_subset = host.Numeric.Count
	//	n_pop    = pop.Numeric.Count
	//	en      = sqrt(n_subset * n_pop / (n_subset + n_pop))
	//	p_value = kolmogorovSurvival((en + 0.12 + 0.11/en) * D)
	//
	// Reuses the same Kolmogorov-survival helper backing TEST_KS
	// (kolmogorovSurvival in internal/processing/test_stat.go) so the overlay and
	// the row-test surface produce identical p-values for the same D + N.
	// The empirical-CDF distance reuses the same `ksTwoSampleD` helper
	// pattern (internal/processing/test_ks.go) — for KS_VS_POP the handler hand-
	// rolls a histogram-edge or percentile-anchor sup-CDF walk because the
	// population view does not retain raw values (see below).
	//
	// Numeric arm only: KS is undefined on categorical distributions
	// (there is no continuous CDF to compare). A categorical host (no
	// numeric payload) fires PULSE_OVERLAY_SCOPE_UNSUPPORTED at runtime
	// (the per-kind validator lives in internal/descriptor/overlay_facet.go; the
	// runtime check is belt-and-braces). Distinct from
	// CHISQ_VS_POP which is DISCRETE-arm only and rejects numeric hosts
	// with PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE — the two kinds
	// partition the FACET-host inferential surface cleanly by host arm.
	//
	// Population-sample availability (KEY DESIGN NOTE — see commit message
	// + skill catalog row): the finalized `FacetPopulationView` exposes
	// ONLY summary state for numeric fields — Welford mean/stdev/count, an
	// optional percentile map, and an optional fixed-width histogram. Raw
	// population values were folded into Welford state at FacetSchema fold
	// time and DISCARDED. KS requires two empirical CDFs, so the handler
	// picks the highest-precision reconstruction available:
	//
	//	  1. Histogram path (PREFERRED — best precision when both arms
	//	     carry a histogram): when host AND population each surface a
	//	     histogram via FacetNumeric.Histogram, the handler aligns bucket
	//	     edges, builds the cumulative bucket-fraction CDF on both sides,
	//	     and computes sup |F_subset(edge_i) - F_pop(edge_i)|. KS
	//	     precision is bounded by bucket width — finer histograms yield
	//	     finer KS distance.
	//	  2. Percentile path (FALLBACK — coarser but always reconstructable
	//	     when both arms requested percentiles): when histograms are
	//	     absent but BOTH arms surface a percentile map via
	//	     FacetNumeric.Percentiles, the handler turns each percentile
	//	     entry into a CDF sample point (`p25` -> CDF=0.25 at the
	//	     percentile's value) and computes sup-CDF-difference over the
	//	     common percentile labels. Lower precision than histograms (a
	//	     handful of CDF samples per side vs hundreds of bucket edges)
	//	     but still well-defined.
	//	  3. Welford-only path (DEGENERATE): when neither histograms nor
	//	     percentiles are available the handler cannot reconstruct an
	//	     empirical CDF — it emits NaN statistic + NaN p-value and one
	//	     layer-level PULSE_OVERLAY_REF_ZERO warning. The caller's
	//	     FacetRequest can lift this case by setting either
	//	     IncludeHistogram=true on both arms or by passing
	//	     NumericPercentiles=["p10","p25","p50","p75","p90"] on both
	//	     arms.
	//
	// FORWARD-COMPAT PRECISION UPLIFT: future work may extend the
	// resolver to retain raw sorted population values when the host
	// FacetRequest names a KS overlay — the handler would then call
	// ksTwoSampleD directly on the raw arms (path 0) and the histogram /
	// percentile fallback would become an opt-out branch. The current
	// implementation is path-agnostic at the dispatch level so adding the
	// raw-value path is a strictly additive change.
	//
	// Inherently buffered (per PRD §2 Non-Goals "Streaming overlay path
	// for inferential kinds"). The streamable subset stays empty for KS
	// because the empirical-CDF construction requires sorted values on
	// both sides; an online folded shape would have to widen the streaming
	// carrier to a heap or a histogram per group. The streamability row in
	// types/overlay_streamability.go is `false` regardless of host
	// streamability.
	//
	// Degenerate inputs:
	//
	//   - Empty host distribution (n_subset == 0) OR empty population
	//     (n_pop == 0): NaN statistic + NaN p-value with one
	//     PULSE_OVERLAY_REF_ZERO warning. No KS distance can be computed
	//     without samples on both sides.
	//   - Host has neither histogram NOR percentiles (the
	//     reconstruction-impossible case above): NaN + NaN with
	//     PULSE_OVERLAY_REF_ZERO. The warning Details carry which knobs
	//     were missing so the caller can audit which to flip on the
	//     FacetRequest.
	//   - Histogram arms with mismatched edges (different Min / Max /
	//     bucket count): handler falls through to the percentile path if
	//     available, else emits PULSE_OVERLAY_REF_ZERO carrying the
	//     mismatching shape Details.
	//
	// Ref handling: `Ref.Population` MUST be populated (the cohort name
	// lives on `Ref.Population.Cohort`); any other ref-family pointer
	// (Margin / Sibling / BaselineIndex / Prior / RollingMean / YoY /
	// Stage / Slot) fires PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE at
	// predict time (per-kind validator lives in
	// internal/descriptor/overlay_facet.go). Mirrors the INDEX_VS_POP /
	// ZSCORE_VS_POP / CHISQ_VS_POP ref contract.
	//
	// Scope must be GROUP. `Level` / `Within` MUST be zero (population
	// comparison is a single-statistic lookup, not an axis prefix); non-
	// zero values fire PULSE_OVERLAY_LEVEL_OUT_OF_RANGE mirroring the
	// implicit-ref family.
	//
	// Renderer-facing shape: the viz developer reads `OverlayPayload.Scalar`
	// for the KS distance D and `OverlaySummary` for the renderer
	// metadata. The recommended rendering is a distributional-shift badge
	// near the facet header carrying the (D, p_value) pair — large D and
	// small p_value flag "the subset distribution shape diverges from the
	// population". The layer-level Baseline stays unset (inferential
	// overlays do not surface a ratio centerpoint; mirrors CHISQ_VS_POP).
	OverlayKindKSVsPop OverlayKind = "OVERLAY_KS_VS_POP"

	// OverlayKindShareOfCol emits a per-cell share-of-column ratio: cell
	// / col_margin. CELL-scoped over a MATRIX (crosstab) host. Cells
	// along a single column sum to 1.0 in the absence of missing cells;
	// renderers can present the layer as a 100%-stacked vertical
	// projection. Structural twin of OVERLAY_SHARE_OF_ROW with the
	// column-axis margin slot as the denominator. Inherently buffered for
	// the same reason as INDEX_VS_MARGIN — the host crosstab
	// orchestrator recomputes margins from raw rows before ApplyOverlays
	// runs.
	OverlayKindShareOfCol OverlayKind = "OVERLAY_SHARE_OF_COL"

	// OverlayKindShareOfRow emits a per-cell share-of-row ratio: cell /
	// row_margin. CELL-scoped over a MATRIX (crosstab) host. Cells along
	// a single row sum to 1.0 in the absence of missing cells; renderers
	// can present the layer as a 100%-stacked horizontal projection.
	// Inherently buffered for the same reason as INDEX_VS_MARGIN — the
	// host crosstab orchestrator recomputes margins from raw rows before
	// ApplyOverlays runs.
	OverlayKindShareOfRow OverlayKind = "OVERLAY_SHARE_OF_ROW"

	// OverlayKindShareOfTotal emits a share-of-grand-total ratio.
	// Dual-shape overload — the dispatch selects the host shape and the
	// runtime handler differs by host:
	//
	//   - MATRIX dispatch: per-cell ratio `cell / grand_total`.
	//     CELL-scoped over a MATRIX (crosstab) host. The entire matrix
	//     sums to 1.0 in the absence of missing cells; renderers can
	//     present the layer as a single-population share projection
	//     where each cell's contribution to the whole table is visible
	//     at a glance. Completes the matrix share triad (row / col /
	//     total). Structural twin of OVERLAY_SHARE_OF_ROW and
	//     OVERLAY_SHARE_OF_COL with the grand-axis margin slot as the
	//     denominator. Buffered (the host crosstab orchestrator
	//     recomputes margins from raw rows before ApplyOverlays runs).
	//     `Ref.Margin` is required (grand-axis-locked even though the
	//     handler ignores the axis value).
	//
	//   - SERIES dispatch: per-group ratio
	//     `group_val / grand_total`, scale 1.0 (no ×100 — emits the raw
	//     share so cells over a complete partition sum to 1.0 within
	//     ULP). GROUP-scoped over a SERIES (grouped Process) host with
	//     SERIES payload — one `SeriesEntry` per host group key in host
	//     order, each carrying the share on `Summary.Statistic`.
	//     Streamable — sibling kind to OVERLAY_INDEX_VS_TOTAL, same
	//     grand-total accumulator (`computeSeriesGrandTotal` in
	//     internal/processing/overlay_series.go) carried alongside the per-group
	//     accumulators in the streaming Process fold (the streaming
	//     orchestrator wires it inline; this kind ships the
	//     post-finalize entry today). `Ref` MUST be empty
	//     (implicit-grand-total); any Ref-family pointer fires
	//     `PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE` at predict time.
	//     Zero `grand_total` emits one `PULSE_OVERLAY_REF_ZERO` warning
	//     and populates every entry's Statistic with NaN. Absent host
	//     groups (resolver reports `(0, false)`) surface a present
	//     SeriesEntry whose Summary leaves Statistic unset and do NOT
	//     contribute to the grand total.
	//
	// The kind-catalog-v1 interview's resolved-decision rule kept the
	// SHARE and INDEX kind names distinct ("readable kind names beat
	// scale-param overloading at JSON-authoring time"), so the SERIES
	// SHARE_OF_TOTAL dispatch is intentionally a separate kind from
	// INDEX_VS_TOTAL even though the math overlaps — callers cannot
	// confuse `share` with `index / 100` at the spec authoring surface.
	OverlayKindShareOfTotal OverlayKind = "OVERLAY_SHARE_OF_TOTAL"

	// OverlayKindCorrespondence runs a simple correspondence analysis
	// (CA) of the host crosstab — a perceptual map of its rows and
	// columns. It takes the SVD (linalg.SVD) of the standardized
	// residual matrix S = D_r^-1/2 (P − r cᵀ) D_c^-1/2 (P the cell
	// shares, r / c the row / column masses). MATRIX-scoped over a
	// MATRIX (crosstab) host, implicit-margin (Ref empty), descriptive
	// (no p-value). Primary payload: a SERIES of principal inertia per
	// dimension (keys dim_1, dim_2, …; share and cumulative share in
	// each entry's Parameters); Summary.Statistic is the total inertia.
	// OverlayPayload.Parts: row_coordinates / column_coordinates (MATRIX
	// points × retained dimensions, synthetic dim_k column keys),
	// row_quality / column_quality (SERIES, cos² summed over the
	// retained dimensions), row_contribution / column_contribution
	// (MATRIX points × dimensions, share of each dimension's inertia).
	// Params: dimensions (default 2, at most min(r, c) − 1) and
	// normalization (symmetric | row_principal | column_principal).
	// Cells must be non-negative counts or sums (AGG_COUNT / AGG_SUM,
	// else PULSE_OVERLAY_NONNEGATIVE_REQUIRED); zero-margin rows and
	// columns are dropped with PULSE_OVERLAY_REF_ZERO. Coordinates are
	// scale-invariant, so a weighted host's Σw table needs no Kish
	// scaling. Signs follow linalg.SVD: per dimension, the dominant
	// component of the column singular vector is positive. Inherently
	// buffered.
	OverlayKindCorrespondence OverlayKind = "OVERLAY_CORRESPONDENCE"

	// OverlayKindMarkov reads the host crosstab as a from-state (row) ×
	// to-state (column) transition count table and projects the flow as
	// a Markov chain. MATRIX-scoped over a MATRIX (crosstab) host,
	// implicit-margin (Ref empty), descriptive (no p-value). The row and
	// column key sets must be equal as sets (aligned by key, never by
	// position; the states take the row order), else
	// PULSE_OVERLAY_MATRIX_NOT_SQUARE. Primary payload: the MATRIX of the
	// row-stochastic transition matrix P (each row's cells over its
	// total; a zero row becomes the unit row — the state absorbs — with a
	// PULSE_OVERLAY_REF_ZERO warning). OverlayPayload.Parts: step_<n>
	// (MATRIX Pⁿ per params.steps), distribution_<n> (SERIES, the initial
	// distribution times Pⁿ; only with params.initial), steady_state
	// (SERIES, power iteration; only for an irreducible aperiodic chain,
	// else the PULSE_OVERLAY_MARKOV_NOT_ERGODIC warning) and
	// absorption_time (SERIES, the expected steps to reach the
	// params.absorbing set, (I − Q)⁻¹·1 through linalg.FactorLU; only
	// with params.absorbing). Params: steps (default [1, 3, 6, 12], each
	// an integer 1–1000), absorbing (state keys) and initial ("margin" or
	// a key → share map). Cells must be non-negative counts or sums
	// (AGG_COUNT / AGG_SUM, else PULSE_OVERLAY_NONNEGATIVE_REQUIRED).
	// Scale-invariant: a weighted host's Σw table needs no Kish scaling.
	// Inherently buffered.
	OverlayKindMarkov OverlayKind = "OVERLAY_MARKOV"

	// OverlayKindRake rakes the host crosstab to target margins by
	// iterative proportional fitting (IPF): rows and columns are scaled in
	// turn until every fitted margin matches its target within
	// params.tolerance (max relative margin error) or params.max_iter
	// sweeps have run. MATRIX-scoped over a MATRIX (crosstab) host,
	// implicit-margin (Ref empty), descriptive (no p-value); it never
	// mutates the host. Params: row_targets and col_targets (host key →
	// value maps covering every host key, else
	// PULSE_OVERLAY_RAKE_TARGET_MISMATCH), targets_as ("shares", the
	// default — normalized and scaled to the host grand total — or
	// "counts", whose row and column totals must agree), max_iter
	// (default 100) and tolerance (default 1e-8). Primary payload: the
	// MATRIX of the fitted table (structural zeros stay zero).
	// OverlayPayload.Parts: factors (MATRIX fitted / observed; null where
	// the observed cell is 0). Summary.Parameters: iterations, residual,
	// converged (1 / 0); a fit short of the tolerance still ships, with a
	// PULSE_OVERLAY_RAKE_NOT_CONVERGED warning. Cells must be
	// non-negative counts or sums (AGG_COUNT / AGG_SUM, else
	// PULSE_OVERLAY_NONNEGATIVE_REQUIRED). Inherently buffered.
	OverlayKindRake OverlayKind = "OVERLAY_RAKE"

	// OverlayKindMatrixGroupSummary summarizes a GROUPED matrix result
	// across its group buckets. It is the first kind on the MATRIX_RESULT
	// host: Ref.Matrix names a Request.Matrices spec by its effective
	// name, and the overlay reads every bucket's Primary
	// (types.MatrixValues; an "upper" encoding is expanded first).
	// MATRIX-scoped, descriptive (no p-value); it never mutates the
	// results. Primary payload: the MATRIX of the per-cell unweighted
	// mean across buckets. OverlayPayload.Parts: min, max, range and
	// n_groups (MATRIX each). The key sets are the union of every
	// bucket's row / column keys; a NaN / null cell contributes nothing,
	// and a cell no bucket contributes to is null. An ungrouped request
	// is PULSE_OVERLAY_GROUPS_REQUIRED. No params. Inherently buffered.
	OverlayKindMatrixGroupSummary OverlayKind = "OVERLAY_MATRIX_GROUP_SUMMARY"

	// OverlayKindStdResidual emits the Haberman adjusted standardized
	// residual of every host crosstab cell,
	// (O − E) / sqrt(E · (1 − r/N) · (1 − c/N)) with E = r·c/N, so a
	// reader sees which cells drive the table's χ² and in which
	// direction. CELL-scoped over a MATRIX (crosstab) host, implicit-
	// margin (Ref empty). Primary payload: a MATRIX of residuals on the
	// host coordinates; OverlayPayload.Parts carries "expected" (the
	// expected counts, MATRIX) and "p" (the two-sided normal p-value of
	// each residual, MATRIX). Inferential: a multiplicity block adjusts
	// the "p" part (layer / row / column / request families). Weighted
	// hosts follow OVERLAY_CHISQ_MATRIX (the Σw table; under kind
	// probability scaled to its Kish n_eff first). A zero-expected cell
	// has an undefined (null) residual and p. Inherently buffered.
	OverlayKindStdResidual OverlayKind = "OVERLAY_STD_RESIDUAL"

	// OverlayKindZScoreVsRolling emits a per-point windowed z-score against
	// the rolling-window mean + sample SD of the W immediately preceding
	// points of an ordered SERIES (grouped Process) host:
	// `zscore_i = (point_value_i - rolling_mean(W)) / rolling_sd(W)`
	// where `rolling_sd = sqrt(M2 / (count - 1))` (SAMPLE SD, n-1
	// denominator). GROUP scope over a SERIES host with SERIES payload —
	// one `SeriesEntry` per host group key in host order, each carrying
	// the z-score on `Summary.Statistic`. Fifth windowed-Process overlay
	// in the catalog (siblings: `OVERLAY_INDEX_VS_PRIOR`,
	// `OVERLAY_INDEX_VS_BASELINE`, `OVERLAY_DELTA_VS_BASELINE`,
	// `OVERLAY_INDEX_VS_ROLLING_MEAN`) and the second
	// consumer of the `Ref.RollingMean` arm of the OverlayRef
	// discriminated union (sibling windowed-rolling family — both kinds
	// carry the window width on `Params["window"]`).
	//
	// Window-via-Params convention: the rolling window width is supplied
	// via `OverlaySpec.Params["window"]` as a positive integer (mirrors
	// the `WIN_*` operator convention; see `skills/window-design.md`).
	// The `Ref.RollingMean` arm is an empty marker struct
	// (`OverlayRollingMeanRef{}`) tagging the ref family — identical to
	// the `OVERLAY_INDEX_VS_ROLLING_MEAN` shape so the validator's
	// "exactly one ref arm populated per kind" contract stays uniform.
	//
	// Variance choice (SAMPLE, not population) — KEY CONTRAST with
	// `OVERLAY_ZSCORE_VS_TOTAL`: the rolling z-score uses SAMPLE SD
	// (divide by `count - 1`, NOT N). The rationale is structural: a
	// rolling window of W observations IS a sample of the wider time
	// series, so unbiased sample variance is the correct convention. By
	// contrast `OVERLAY_ZSCORE_VS_TOTAL` uses POPULATION SD (`sqrt(M2 /
	// N)`) because the per-group aggregation set IS the whole population
	// being standardised against. The two surfaces are intentionally
	// orthogonal: rolling = local sample; total = global population. The
	// `OVERLAY_INDEX_VS_ROLLING_MEAN` carrier stores the Welford
	// `(count, mean, M2)` trio precisely so this kind can lift the
	// rolling SD via `sqrt(M2 / (count - 1))` without re-folding.
	//
	// Math (per host group ordinal `i`):
	//
	//	W = Params["window"] (positive int)
	//	if fewer than 2 PRESENT prior points in the window
	//	                                                  ⇒ NaN (no warning)
	//	if rolling_sd(W) == 0                             ⇒ NaN + PULSE_OVERLAY_REF_ZERO
	//	otherwise                                         ⇒ (point - mean) / sd
	//
	// Carrier shape (shared with `OVERLAY_INDEX_VS_ROLLING_MEAN`): the
	// handler maintains the same per-group ring buffer of the W most
	// recently observed PRESENT values plus the Welford-Pébaÿ (count,
	// mean, M2) trio updated alongside each push/evict. INDEX_VS_ROLLING_MEAN
	// reads only `mean`; ZSCORE_VS_ROLLING reads BOTH `mean` and `M2`. The
	// shared carrier keeps the per-group accumulator footprint flat as
	// more rolling-family kinds land.
	//
	// Window-fill semantics: when the carrier `count < 2` (the Welford
	// recurrence requires at least two observations to define a sample
	// variance), the handler emits NaN without warning — "window not yet
	// filled with at least 2 priors" is structurally distinct from
	// "denominator was zero" (mirrors the `OVERLAY_INDEX_VS_ROLLING_MEAN`
	// window-not-yet-filled rule). When the host series is shorter than W
	// (no ordinal ever sees a full window) every entry's Statistic is NaN
	// with no warning.
	//
	// Absent-point policy (ring buffer does not advance): an absent host
	// ordinal (resolver reports `(0, false)`) emits a present
	// `SeriesEntry` whose Summary leaves Statistic unset and DOES NOT
	// advance the ring buffer. Mirrors the
	// `OVERLAY_INDEX_VS_ROLLING_MEAN` / `OVERLAY_INDEX_VS_PRIOR` absent-
	// point carrier rule — the next present ordinal will compare against
	// the most recent W PRESENT values, not absent slots.
	//
	// Zero rolling-SD path: when the rolling SD is exactly `0` at the
	// divide step (e.g. every prior point in the window has the same
	// value — constant series), the handler emits ONE
	// `PULSE_OVERLAY_REF_ZERO` warning per layer and surfaces NaN on the
	// affected entry. Subsequent points may again hit the zero-SD path
	// as the ring rolls; one warning per layer per zero-SD event
	// occurrence. Mirrors the share / index / zscore family's zero-
	// denominator contract.
	//
	// Window param validation: `Params["window"]` MUST be present and
	// MUST be a positive integer (JSON numbers decoded as float64 are
	// accepted when integral). Missing param fires
	// `PULSE_OVERLAY_PARAM_MISSING` carrying `{kind, param}` Details at
	// both predict (`descriptor.validateOverlayZScoreVsRolling`) and
	// runtime (`processing.applyZScoreVsRolling`). Window `<= 0` fires
	// `PULSE_OVERLAY_LEVEL_OUT_OF_RANGE` carrying `{window}` Details —
	// the LEVEL_OUT_OF_RANGE code is reused for "value out of valid
	// range" semantics so the new code surface stays narrow (mirrors the
	// existing usage on Level / Within slots).
	//
	// Ref handling: `Ref.RollingMean` MUST be populated (empty struct is
	// fine; the marker tags the ref family). Any other ref-family
	// pointer (`Margin` / `Sibling` / `BaselineIndex` / `Prior` /
	// `Population` / `Stage` / `Slot`) fires
	// `PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE` at predict time.
	//
	// Scope must be GROUP. `Level` / `Within` MUST be zero (windowed
	// kind — the rolling-window carrier folds across the ordered axis
	// without a prefix-bucket denominator; non-zero values fire
	// `PULSE_OVERLAY_LEVEL_OUT_OF_RANGE` mirroring the
	// `INDEX_VS_ROLLING_MEAN` / `INDEX_VS_PRIOR` / `INDEX_VS_BASELINE` /
	// `INDEX_VS_TOTAL` implicit-margin / windowed family).
	//
	// Buffered. Per `types/overlay_streamability.go`, the streamability
	// row is `false` — the ring buffer carries the full window of present
	// values plus the Welford trio per group, which the streaming Process
	// pass cannot maintain inline with the per-record fold today (matches
	// the `OVERLAY_INDEX_VS_ROLLING_MEAN` buffered rationale verbatim).
	// Forward-compat: future work may lift the rolling carrier into a
	// streaming-aware shape; when that lands the streamability flag flips
	// to true.
	//
	// Chan-Welford merge documentation (per CLAUDE.md § Execution modes
	// → Parallel buffered Process): the Welford triple combines under
	// Chan-Welford with the standard `delta = mean_B - mean_A;
	// mean = mean_A + delta * n_B/n;
	// M2 = M2_A + M2_B + delta² * n_A*n_B/n` recurrence. v1 ships
	// serial-per-group execution so the merge path is not exercised
	// today, but the carrier shape stays parallel-safe so future work
	// that lifts the rolling fold into the parallel buffered Process
	// pipeline can reuse the existing merge plumbing.
	//
	// Renderers centre diverging colour ramps on `baseline = 0` (mirrors
	// `OVERLAY_ZSCORE_VS_TOTAL` / `OVERLAY_ZSCORE_VS_MARGIN` — every
	// z-score family produces a centred distribution, not a ratio).
	OverlayKindZScoreVsRolling OverlayKind = "OVERLAY_ZSCORE_VS_ROLLING"

	// OverlayKindZScoreVsPop emits a per-value population-comparison
	// z-score against a FACET host: `z = (subset_freq - pop_freq) / sd_pop`
	// for each value of the host Facet field. GROUP scope over a FACET
	// host with SERIES payload — one `SeriesEntry` per host value in
	// payload order, each carrying the z-score on `Summary.Statistic`.
	// Sibling streamable FACET-host kind to `OVERLAY_INDEX_VS_POP`
	// (OVERLAY_INDEX_VS_POP); pairs with that kind as the two streamable Facet overlay
	// kinds — a viz developer requesting both together gets two parallel
	// series layers from a single Facet pass.
	//
	// Math:
	//
	//   Discrete host: subset_freq = host.Discrete.Values[v].Count /
	//     sum(host.Discrete.Values[*].Count); pop_freq =
	//     FacetPopulationView.DiscreteFrequency(v); sd_pop =
	//     FacetPopulationView.DiscreteFrequencyStdev() (population SD
	//     across the population's per-category frequencies — Welford-
	//     Pébaÿ accumulator already used by FacetSchema, surfaced by the
	//     resolver via DiscreteCounts() walk).
	//
	//   Numeric host: subset_val and pop_mean / pop_sd come from the
	//     respective FacetNumeric.Mean / StdDev slots. The per-bin path
	//     would require a histogram on both host and pop and matches the
	//     INDEX_VS_POP numeric shape — but unlike INDEX_VS_POP which
	//     reads bin frequencies, ZSCORE_VS_POP operates on the values
	//     themselves so the numeric path reads the Welford summary
	//     directly. Each bin's center value standardised against the
	//     population's Welford (mean, sd) producing the per-bin z-score.
	//
	// On `sd_pop == 0`: emit ONE warning code `PULSE_OVERLAY_REF_ZERO`
	// per affected entry and SKIP the z-score entry (Statistic stays
	// unset on that entry — "present slot, empty summary" shape).
	// Mirrors the INDEX_VS_POP zero-pop_freq contract.
	//
	// Absent-population path: when the resolver could not find any
	// population entry for `value` (the value never appeared in the
	// population dictionary), the handler treats it as the zero-pop_freq
	// case and emits the same warning + skip behavior (mirrors
	// INDEX_VS_POP).
	//
	// Ref handling: `Ref.Population` MUST be populated (mirrors
	// INDEX_VS_POP). Any other ref-family pointer (`Margin` / `Sibling` /
	// `BaselineIndex` / `Prior` / `RollingMean` / `YoY` / `Stage` /
	// `Slot`) fires `PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE` at
	// predict time (per-kind validator lives in internal/descriptor/overlay_facet.go).
	//
	// Scope must be GROUP. `Level` / `Within` MUST be zero (population
	// comparison is a single-value lookup, not an axis prefix); non-zero
	// values fire `PULSE_OVERLAY_LEVEL_OUT_OF_RANGE` mirroring the
	// implicit-ref family.
	//
	// Streamable. Per `types/overlay_streamability.go`, the streamability
	// row is `true` — the handler runs as a post-finalize fold over the
	// host's already-materialized per-value distribution + the resolver's
	// already-materialized population view (sd_pop derives from the
	// Welford accumulator FacetSchema already folded for the population
	// cohort). The host-side streaming Facet pass keeps its existing
	// online accumulators (Welford trio / per-value count map); the
	// overlay does NOT widen the streaming carrier — it consumes
	// finalized state only. Streamable matches the kind-catalog-v1
	// "Streaming-capable subset" — pairs with `OVERLAY_INDEX_VS_POP` as
	// the two streamable Facet kinds.
	//
	// Renderers centre diverging colour ramps on `baseline = 0` (mirrors
	// `OVERLAY_ZSCORE_VS_MARGIN` / `OVERLAY_ZSCORE_VS_TOTAL` /
	// `OVERLAY_ZSCORE_VS_ROLLING` — every z-score family produces a
	// centred distribution, not a ratio).
	OverlayKindZScoreVsPop OverlayKind = "OVERLAY_ZSCORE_VS_POP"

	// OverlayKindZScoreVsMargin emits a per-cell standardized-margin
	// z-score: (cell - margin) / sd where margin is the matching axis
	// margin slot and sd is the population standard deviation of the
	// cell values within the same margin slice. CELL-scoped over a
	// MATRIX (crosstab) host. Unlike the SHARE_OF_* triad (each of
	// which is structurally axis-locked), ZSCORE_VS_MARGIN supports
	// every axis a Margin reference can target (row / column / grand);
	// callers pick the axis explicitly via Ref.Margin.Axis and the
	// handler dispatches the matching slice. First non-ratio overlay
	// in the catalog — output is unitless deviation, not a ratio or
	// percentage. Inherently buffered for the same reason as
	// INDEX_VS_MARGIN — both the host crosstab path and the per-slice
	// Welford recurrence rely on a fully-materialised matrix.
	OverlayKindZScoreVsMargin OverlayKind = "OVERLAY_ZSCORE_VS_MARGIN"

	// OverlayKindYoY emits a per-point year-over-year ratio against the
	// same period one year prior in an ordered SERIES (grouped Process)
	// host whose grouper is `GROUP_DATE`. GROUP scope over a SERIES host
	// with SERIES payload — one `SeriesEntry` per host group key in host
	// order, each carrying the YoY ratio on `Summary.Statistic`. Sixth
	// windowed-Process overlay in the catalog (siblings:
	// `OVERLAY_INDEX_VS_PRIOR`, `OVERLAY_INDEX_VS_BASELINE`,
	// `OVERLAY_DELTA_VS_BASELINE`, `OVERLAY_INDEX_VS_ROLLING_MEAN`,
	// `OVERLAY_ZSCORE_VS_ROLLING`) and the first consumer of the empty
	// `Ref.YoY` marker arm of the OverlayRef discriminated union.
	//
	// Math (per host group ordinal `i`):
	//
	//	frequency = spec.Params["frequency"] OR req.Groups[0].Params["frequency"]
	//	prior_i = lookup for the host series point at "i - <stride>" based on
	//	          frequency:
	//	            annual    ⇒ i - 1
	//	            quarterly ⇒ i - 4
	//	            monthly   ⇒ i - 12
	//	            weekly    ⇒ i - 52
	//	            daily     ⇒ exact-key lookup against host key index at
	//	                        host.Key(i).AddDate(-1, 0, 0); Feb 29 in a
	//	                        non-leap prior year emits NaN (no exact-key
	//	                        match — explicit non-goal: no day-of-week or
	//	                        leap-year realignment in v1).
	//	            hourly    ⇒ exact-key lookup against host key index at
	//	                        host.Key(i).Add(-365*24*time.Hour) with the
	//	                        same exact-key rule.
	//	if !present_at(prior_i)  ⇒ NaN (first year of data is legitimate —
	//	                            "no comparison available" rather than
	//	                            "denominator was zero"; no warning)
	//	if prior_value == 0      ⇒ NaN + PULSE_OVERLAY_REF_ZERO warning
	//	otherwise                ⇒ point_value / prior_value * 100
	//
	// Required GROUP_DATE host grouper: the kind only operates against a
	// SERIES host whose single grouper is `GROUP_DATE`. Other grouper
	// kinds (CATEGORY / RANGE / ROUNDED / QUANTILE / SET_VALUE) cannot
	// resolve the "same period one year prior" semantics — predict
	// (`descriptor.validateOverlayYoY`) and runtime (the handler's host
	// introspection arm via `SeriesHostView.GrouperKind`) both reject
	// non-DATE hosts with `PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE`.
	//
	// Required `frequency` Param: the kind cannot infer the correct prior-
	// period stride from the GROUP_DATE `component` slot alone because
	// the per-component stride for "one year prior" varies by component
	// (annual ⇒ 1, quarterly ⇒ 4, monthly ⇒ 12, weekly ⇒ 52, daily ⇒
	// 365-day calendar arithmetic, hourly ⇒ 365×24-hour arithmetic). The
	// handler reads the explicit `frequency` value from
	// `spec.Params["frequency"]` first (the YoY's own override) and falls
	// back to `req.Groups[0].Params["frequency"]` (the canonical GROUP_DATE
	// authoring slot). Missing both fires
	// `PULSE_OVERLAY_YOY_FREQUENCY_MISSING` with `{kind, host_grouper}`
	// Details at both predict and runtime. Outside the supported set
	// (`annual` | `quarterly` | `monthly` | `weekly` | `daily` | `hourly`)
	// fires `PULSE_OVERLAY_YOY_INCOMPATIBLE_FREQUENCY` with
	// `{frequency, supported}` Details.
	//
	// Calendar-week / day-of-week realignment is an explicit non-goal in
	// v1: weekly frequency uses calendar-week-aligned `i - 52` arithmetic
	// (no day-of-week realignment); daily frequency uses exact-key lookup
	// against the host key index after subtracting one year via
	// `time.Time.AddDate(-1, 0, 0)` (Feb 29 in a non-leap prior year
	// emits NaN — no exact-key match). The runtime documents both rules
	// explicitly so callers do not silently get realigned results.
	//
	// Absent-point policy: a host that did not produce a value for group
	// `i` (the resolver returns `(0, false)`) surfaces a `SeriesEntry`
	// whose `Summary` leaves `Statistic` unset — the canonical "present
	// slot, empty summary" shape from the SERIES dispatch contract.
	// Absent groups do NOT participate in the YoY computation. The first
	// year of data (every ordinal whose prior-year index lands at < 0 OR
	// whose daily/hourly prior-year date does not match an exact host
	// key) emits NaN without warning — "no comparison available" is
	// structurally distinct from "denominator was zero" (mirrors the
	// `OVERLAY_INDEX_VS_PRIOR` first-point NaN rule).
	//
	// Zero-prior path: when the resolved prior value is `0` at the divide
	// step (legitimate prior point with a zero post-filter sum) the
	// handler emits ONE `PULSE_OVERLAY_REF_ZERO` warning per layer and
	// surfaces NaN on the affected entry. Mirrors the share / index /
	// zscore family's zero-denominator contract (one warning per layer,
	// not per cell).
	//
	// Ref handling: `Ref.YoY` MUST be populated (empty marker is fine —
	// the v1 frequency value lives on Params per the WIN_* operator
	// convention). Any other ref-family pointer (`Margin` / `Sibling` /
	// `BaselineIndex` / `Prior` / `RollingMean` / `Population` / `Stage` /
	// `Slot`) fires `PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE`.
	//
	// Scope must be GROUP. `Level` / `Within` MUST be zero (windowed
	// kind — the prior-period lookup folds across the ordered axis
	// without a prefix-bucket denominator); non-zero values fire
	// `PULSE_OVERLAY_LEVEL_OUT_OF_RANGE` mirroring the
	// `INDEX_VS_PRIOR` / `INDEX_VS_BASELINE` / `INDEX_VS_ROLLING_MEAN`
	// family.
	//
	// Buffered. Per `types/overlay_streamability.go`, the streamability
	// row is `false` — the prior-period lookup requires the materialised
	// host series (daily / hourly arms walk an exact-key index over the
	// full host key list; coarser frequencies index into an arbitrary
	// prior ordinal). The handler runs at the buffered post-host-
	// finalize exit via `ApplyOverlaysSeries`. Forward-compat: a future
	// story may lift the per-frequency lookup into a streaming-aware
	// shape when the streaming-Process orchestrator carries an exact-key
	// host index inline.
	//
	// Renderers centre diverging colour ramps on `baseline = 100`
	// (mirrors `OVERLAY_INDEX_VS_MARGIN` / `OVERLAY_INDEX_VS_TOTAL` /
	// `OVERLAY_INDEX_VS_SIBLING` / `OVERLAY_INDEX_VS_PRIOR` /
	// `OVERLAY_INDEX_VS_BASELINE` / `OVERLAY_INDEX_VS_ROLLING_MEAN`).
	OverlayKindYoY OverlayKind = "OVERLAY_YOY"

	// OverlayKindZScoreVsTotal emits a per-group standardized z-score
	// against the host series' grand-total distribution: for each host
	// group key the layer surfaces `(group_val - mean) / sd` where
	// `mean = Σ_j group_val[j] / N` and `sd = sqrt(M2 / N)` (population
	// variance) folded across the N present per-group aggregated values.
	// GROUP scope over a SERIES (grouped Process) host with SERIES
	// payload — one SeriesEntry per host group key in host order, each
	// carrying the z-score on `Summary.Statistic`. Third and final
	// streamable overlay in the grouped-Process subset (sibling to
	// OVERLAY_INDEX_VS_TOTAL and the SERIES dispatch of
	// OVERLAY_SHARE_OF_TOTAL): the Welford accumulator is one (count,
	// mean, M2) triple carried alongside the per-group accumulators
	// inside the streaming Process fold — no second pass over records,
	// the post-host finalize emits `(group_val - mean) / sd` per group.
	//
	// Math (per host group i):
	//
	//	count       = number of present per-group values
	//	mean        = Σ_j group_val[j] / count       (Welford recurrence,
	//	                                              single-pass)
	//	M2          = Σ_j (group_val[j] - mean)²    (Welford accumulator)
	//	sd          = sqrt(M2 / count)               (population SD)
	//	zscore_i    = (group_val[i] - mean) / sd
	//
	// Variance choice (population, not sample): the kind name says
	// `_VS_TOTAL` which implies the host's per-group aggregation set IS
	// the whole population we are standardising against — we are not
	// inferring a wider population from a sample of groups, we are
	// standardising every present group against the entire observed
	// distribution. Population variance (divide by N, not N-1) is the
	// correct convention; the sibling buffered `ATTR_ZSCORE` attribute
	// reuses the same convention against raw records. Reuses the same
	// numerical convention (single-pass Welford-Pébaÿ) as the parallel
	// buffered Process path and the crosstab ZSCORE_VS_MARGIN handler so
	// cross-mode equivalence tests stay byte-equal within ULP.
	//
	// Zero-variance path: when `sd == 0` (every present group value is
	// equal, including the every-group-zero degenerate case and the
	// single-present-group case) the handler emits ONE
	// PULSE_OVERLAY_REF_ZERO warning and populates every entry's
	// `Summary.Statistic` with NaN. Mirrors the existing
	// PULSE_OVERLAY_REF_ZERO contract used by the share / index family
	// against a missing axis margin on the MATRIX host AND the sibling
	// SERIES kinds against a zero grand total.
	//
	// Absent-group policy: a host that did not produce a record for
	// group i (the resolver returns (0, false)) surfaces a SeriesEntry
	// whose Summary leaves Statistic unset — the canonical "present
	// slot, empty summary" shape established by the SERIES
	// dispatch contract. Absent groups do NOT contribute to the
	// Welford accumulator (the resolver gates the fold the same way it
	// gates per-group emission, identical to INDEX_VS_TOTAL).
	//
	// Ref handling: implicit-grand-total. The Ref union is left EMPTY —
	// the kind's centerpoint is the host series' own grand-total
	// distribution (mean), so callers supplying any Ref family pointer
	// (Margin / Sibling / BaselineIndex / Population / Stage / Slot)
	// fail PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE at predict time
	// (mirrors INDEX_VS_TOTAL / SHARE_OF_TOTAL SERIES contract).
	//
	// Scope is GROUP (not CELL or ROW): the kind decorates each grouper
	// level the host emits. The validator rejects any other scope.
	//
	// Streamable. Per types/overlay_streamability.go, the streamability
	// row is `true` — the Welford accumulator (count + mean + M2) is
	// three f64s carried alongside the per-group accumulators inside
	// the streaming Process fold, and the standardisation step happens
	// at host finalize. The streaming-Process orchestrator wires the
	// inner per-record hook; this kind ships with a SERIES-host
	// post-finalize entry (ApplyOverlaysSeries route) so the streaming-
	// vs-buffered byte-identity test holds at the entry-point level
	// today. Gotcha: the streaming pass
	// folds Welford over GROUPS, not raw records — variance is across
	// N groups, not N records, distinct from `ATTR_ZSCORE`'s record-
	// level semantics.
	OverlayKindZScoreVsTotal OverlayKind = "OVERLAY_ZSCORE_VS_TOTAL"

	// OverlayKindIndexVsRef is the COMPOSE-host dual-shape ratio index
	// of each target slot's value against the matching reference slot
	// value: `(target / ref) * scale` where `scale` defaults to `100`
	// (set `Params["scale"] = 1` for a raw ratio). Dual-shape catalog
	// row — the host-shape disambiguator (matrix vs series) routes the
	// per-coordinate / per-group dispatch:
	//
	//   - MATRIX host: CELL scope over a MATRIX (crosstab) host
	//     with MATRIX payload. Per-cell ratio at `(rowKey, colKey)`.
	//   - SERIES host: GROUP scope over a SERIES (grouped Process)
	//     host with SERIES payload. Per-group ratio at the host's
	//     group key.
	//
	// First COMPOSE-only crosstab-shape overlay kind in the catalog
	// and the first kind to consume the
	// `ComposeOverlaySpec.Reference` / `Targets` slot-label pair across
	// both MATRIX and SERIES slots. Sibling kind to
	// `OVERLAY_DELTA_VS_REF` (subtractive twin sharing the SERIES arm).
	//
	// Math (per host coordinate `(i, j)` for MATRIX, `i` for SERIES):
	//
	//	target_val = target_slot.<MatrixCell|SeriesValue>(i, j)
	//	ref_val    = ref_slot.<MatrixCell|SeriesValue>(i, j)
	//	scale      = Params["scale"] (default 100, accepts 1 for raw ratio)
	//	if ref_val == 0 ⇒ NaN + PULSE_OVERLAY_REF_ZERO warning
	//	otherwise       ⇒ (target / ref) * scale
	//
	// Streamable. Per `types/overlay_streamability.go` the row is
	// `true` — the SERIES dispatch is fold-only (single accumulator per
	// group; no peer-cell lookup) and matches the kind-catalog-v1
	// "Streaming-capable subset". The MATRIX dispatch remains forced
	// buffered by the slot barrier in `internal/service.Compose` /
	// `internal/service.ComposeParallel`; the flag describes the kind's
	// INTRINSIC streaming capability (mirrors the
	// `OVERLAY_SHARE_OF_TOTAL` dual-shape convention — MATRIX-arm
	// routes through `canFuseCrosstab`'s overlays-force-buffered arm,
	// SERIES-arm rides the streaming Process pass). Renderers centre
	// diverging colour ramps on `baseline = scale` (default `100`
	// mirrors the per-Request `INDEX_VS_*` family).
	OverlayKindIndexVsRef OverlayKind = "OVERLAY_INDEX_VS_REF"

	// OverlayKindDeltaVsRef is the COMPOSE-host dual-shape additive
	// delta of each target slot's value against the matching reference
	// slot value: `target - ref`. Dual-shape catalog row — the
	// host-shape disambiguator (matrix vs series) routes the
	// per-coordinate / per-group dispatch:
	//
	//   - MATRIX host: CELL scope over a MATRIX (crosstab) host
	//     with MATRIX payload. Per-cell delta at `(rowKey, colKey)`.
	//   - SERIES host: GROUP scope over a SERIES (grouped Process)
	//     host with SERIES payload. Per-group delta at the host's
	//     group key.
	//
	// Subtractive twin of `OVERLAY_INDEX_VS_REF`; shares the same
	// reference / target resolution pipeline and the same
	// key-alignment / schema-match / dict-prefix gates.
	//
	// Math (per host coordinate `(i, j)` for MATRIX, `i` for SERIES):
	//
	//	target_val = target_slot.<MatrixCell|SeriesValue>(i, j)
	//	ref_val    = ref_slot.<MatrixCell|SeriesValue>(i, j)
	//	delta      = target_val - ref_val
	//
	// Unlike the `OVERLAY_INDEX_VS_REF` sibling (which divides by the
	// reference value and emits `PULSE_OVERLAY_REF_ZERO` against a zero
	// denominator), `OVERLAY_DELTA_VS_REF` performs subtraction and is
	// mathematically defined for every finite reference value including
	// zero — the handler does NOT emit `PULSE_OVERLAY_REF_ZERO` on zero
	// references. Mirrors the per-Request DELTA family rule
	// (`OVERLAY_DELTA_VS_MARGIN` / `OVERLAY_DELTA_VS_BASELINE` /
	// `OVERLAY_DELTA_VS_SIBLING`). Missing reference values (target
	// carries a key the reference did not surface) still emit a
	// `PULSE_OVERLAY_REF_ZERO` with a `ref_missing=true` Detail flag —
	// the same missing-key warning shape the MATRIX arm uses.
	//
	// Output preserves the target slot's units — a $-valued AGG_SUM
	// target cell minus a $-valued reference cell yields a $-valued
	// deviation in the same currency. Renderers centre diverging colour
	// ramps on `baseline = 0` (mirrors the rest of the DELTA family on
	// other host shapes).
	//
	// Streamable. Per `types/overlay_streamability.go` the row is
	// `true` — the SERIES dispatch is fold-only (single accumulator
	// per group; no peer-cell lookup) and matches the kind-catalog-v1
	// "Streaming-capable subset". The MATRIX dispatch remains forced
	// buffered by the slot barrier in `internal/service.Compose` /
	// `internal/service.ComposeParallel`; the flag describes the kind's
	// INTRINSIC streaming capability (mirrors the
	// `OVERLAY_INDEX_VS_REF` dual-shape convention).
	OverlayKindDeltaVsRef OverlayKind = "OVERLAY_DELTA_VS_REF"

	// OverlayKindPropZCell is the COMPOSE-host per-cell two-proportion
	// z-test against the reference slot's matching cell. CELL scope over
	// a MATRIX (crosstab) host with MATRIX payload — each cell's value
	// is the two-sided p-value as a float64. Cells are treated as
	// success counts; the reference cell's matching row margin is
	// treated as the sample size on the reference side, and the target
	// cell's matching row margin is treated as the sample size on the
	// target side. The two-proportion z-test reuses the same pooled-
	// standard-error formula that backs `TEST_PROP_Z` (see
	// `internal/processing/test_propz.go`):
	//
	//	p_target = target_cell / target_row_margin
	//	p_ref    = ref_cell    / ref_row_margin
	//	pooled   = (target_cell + ref_cell) / (target_row_margin + ref_row_margin)
	//	se       = sqrt(pooled * (1 - pooled) * (1/n_target + 1/n_ref))
	//	z        = (p_target - p_ref) / se
	//	p_value  = 2 * (1 - Φ(|z|))
	//
	// Reuses the `standardNormalCDF` helper backing `TEST_PROP_Z` so the
	// overlay and the row-test surface produce identical p-values for
	// the same (success, n) pair.
	//
	// Degenerate inputs (pooled = 0 or 1, missing row margin, etc.)
	// produce NaN p-values with a `PULSE_OVERLAY_REF_ZERO` warning per
	// affected cell carrying the offending diagnostic. Mirrors the
	// `OVERLAY_FISHER_EXACT_CELL` cell-level warning emission shape.
	//
	// Buffered. Inferential overlays as a family stay buffered until a
	// streamable-test path is plumbed (PRD §2 Non-Goals "Streaming
	// overlay path for inferential kinds").
	OverlayKindPropZCell OverlayKind = "OVERLAY_PROP_Z_CELL"

	// OverlayKindPropZPanel is the COMPOSE-host multi-reference per-cell
	// pairwise two-proportion z-test across N + 1 slots (the reference
	// slot plus every target slot). CELL scope over a MATRIX (crosstab)
	// host with MATRIX payload — each cell's `Value` is NOT a scalar
	// p-value but the flattened upper-triangular slice of pairwise
	// two-sided p-values across the panel's N + 1 slots. First multi-ref
	// COMPOSE-only kind in the catalog and the first kind to
	// emit a per-cell vector payload via `MatrixCell.Value` carrying a
	// `[]float64` (the scalar `MatrixCell.Value any` slot accepts the
	// vector shape verbatim — same precedent the RichAggregator family
	// uses for map / slice cell values).
	//
	// Slot ordering: the panel ordering is `{reference, targets[0],
	// targets[1], ..., targets[N-1]}` — index 0 is the reference, every
	// subsequent index is one target slot in `ComposeOverlaySpec.Targets`
	// order. The handler reads each slot's matching cell at `(rowKey,
	// colKey)` and folds N + 1 (count, total) pairs into the pairwise
	// matrix.
	//
	// Output shape — flattened upper-triangular slice (row-major, NO
	// diagonal): for an `M = N + 1` slot panel, the per-cell `[]float64`
	// carries the pairs in canonical `(i, j)` order with `i < j`:
	//
	//	[(0,1), (0,2), ..., (0,M-1), (1,2), ..., (1,M-1), ..., (M-2,M-1)]
	//
	// The slice length is `M * (M - 1) / 2`. Index helper:
	//
	//	pairIndex(i, j, M) = i * (2*M - i - 1) / 2 + (j - i - 1)
	//
	// The diagonal is implicit (every diagonal entry is `1.0` —
	// self-vs-self) and the lower triangular is implicit (`p[j, i] ==
	// p[i, j]` — symmetric matrix). Renderers reconstruct the dense
	// matrix from the flattened slice via the pair index helper.
	// Documented in `skills/overlay-system.md`.
	//
	// Math (per pair `(i, j)`): the same pooled-SE two-proportion z-test
	// formula `OVERLAY_PROP_Z_CELL` uses via the shared
	// `twoProportionZ` helper. Each slot's matching row margin is its
	// sample size; the helper accepts `(success_i, n_i, success_j, n_j)`
	// and returns the two-sided p-value. Reuses the same
	// `standardNormalCDF` helper backing `TEST_PROP_Z` so every pairwise
	// p-value matches the corresponding `OVERLAY_PROP_Z_CELL` output
	// byte-for-byte.
	//
	// Cap enforcement — `OverlayOptions.MaxPanelTargets`: panel
	// combinatorics scale O(N²) per cell, so the handler enforces a
	// caller-attested cap on the number of target slots. The cap
	// defaults to `16` when `ComposeOverlaySpec.Options` is nil OR
	// `Options.MaxPanelTargets == 0`. `len(spec.Targets) >
	// MaxPanelTargets` fires `PULSE_OVERLAY_PANEL_TARGETS_OVER_CAP` at
	// handler entry with `{observed, cap}` Details. Per the interview
	// risk paragraph "Multi-reference combinatorics", bumping the
	// default 16 requires explicit interview update — `Options` is the
	// per-request override surface for callers who need a larger panel
	// today.
	//
	// Degenerate inputs: missing row margins fall back to the cell value
	// as the sample size (mirrors `OVERLAY_PROP_Z_CELL`); pairwise
	// `(pooled ∈ {0, 1}, se == 0)` produces NaN at the affected pair
	// position with one `PULSE_OVERLAY_REF_ZERO` warning per (cell,
	// pair) tuple. Cells where the reference value is absent on any
	// slot surface an empty (nil) per-cell vector with one
	// `PULSE_OVERLAY_REF_ZERO` warning carrying `ref_missing: true`.
	//
	// Buffered. Inferential overlays as a family stay buffered until a
	// streamable-test path is plumbed (PRD §2 Non-Goals).
	OverlayKindPropZPanel OverlayKind = "OVERLAY_PROP_Z_PANEL"

	// OverlayKindPairwiseProbitT is the intra-matrix axis-pairwise probit
	// t-test (syndicated meaningfulness / uniqueness family). Per opposite-
	// axis position it transforms each leg's proportion through Φ⁻¹ and
	// tests the difference: t = (Φ⁻¹(p_i) - Φ⁻¹(p_j)) / sqrt(1/n_i + 1/n_j)
	// against Student-t with df = n_i + n_j - 2, two-sided. Reuses the
	// Student-t survival helper backing TEST_T. Reads proportion + n per
	// leg (p_source / n_source). See the OVERLAY_PAIRWISE_* family note.
	OverlayKindPairwiseProbitT OverlayKind = "OVERLAY_PAIRWISE_PROBIT_T"

	// OverlayKindPairwisePropZ is the intra-matrix axis-pairwise pooled-SE
	// two-proportion z-test (custom / A&U / syndicated top2box family). Per
	// opposite-axis position it tests leg i vs leg j via the same
	// twoProportionZ helper backing OVERLAY_PROP_Z_CELL, so p-values match
	// byte-for-byte. Reads proportion + n per leg (p_source / n_source).
	// See the OVERLAY_PAIRWISE_* family note.
	OverlayKindPairwisePropZ OverlayKind = "OVERLAY_PAIRWISE_PROP_Z"

	// OverlayKindPairwiseTwoMeansZ is the intra-matrix axis-pairwise
	// two-means z-test on AGG_WELFORD cells (AU Q137/Q140/Q141 family). Per
	// opposite-axis position it tests mean_i vs mean_j using the Welford
	// triple {mean, variance, n} on CellComponents with a normal-CDF tail
	// (no df adjustment): z = (m_i - m_j) / sqrt(v_i/n_i + v_j/n_j). Reuses
	// standardNormalCDF. A non-Welford host fails fast with
	// PULSE_OVERLAY_SHAPE_MISMATCH. See the OVERLAY_PAIRWISE_* family note.
	OverlayKindPairwiseTwoMeansZ OverlayKind = "OVERLAY_PAIRWISE_TWO_MEANS_Z"

	// OverlayKindPairwiseWeightedTwoMeansZ is the intra-matrix
	// axis-pairwise two-means z-test on AGG_WEIGHTED_MEAN cells. Per
	// opposite-axis position it tests weighted_mean_i vs weighted_mean_j
	// from the weighted moments {weighted_mean, m2_weighted, sum_weights,
	// sum_weights_sq} on CellComponents, with a normal-CDF tail:
	// z = (m_i - m_j) / sqrt(var_i/n_i + var_j/n_j). The REQUIRED
	// params.n_basis picks the convention (no default):
	//   - "weights": var = m2/(Σw - 1), n = Σw (frequency weights);
	//   - "kish":    var = m2/(Σw - Σw²/Σw), n = (Σw)²/Σw² (Kish n_eff).
	// The universal-floor n is never read — it counts null / zero-weight
	// rows. A non-weighted-mean host fails fast with
	// PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE; n_source / p_source are
	// refused (PULSE_OVERLAY_PARAM_MISSING). Unlike the AGG_WELFORD
	// sibling, the cell aggregator is mergeable, so the crosstab stays on
	// the fused path. See the OVERLAY_PAIRWISE_* family note.
	OverlayKindPairwiseWeightedTwoMeansZ OverlayKind = "OVERLAY_PAIRWISE_WEIGHTED_TWO_MEANS_Z"

	// OverlayKindPairwiseWelchT is the intra-matrix axis-pairwise
	// Welch–Satterthwaite t-test on AGG_WELFORD cells (AU Q99 family). Per
	// opposite-axis position it tests mean_i vs mean_j using the Welford
	// triple {mean, variance, n} with the Welch SE and Satterthwaite df,
	// two-sided via the Student-t survival helper backing TEST_T /
	// TEST_WELCH. A non-Welford host fails fast with
	// PULSE_OVERLAY_SHAPE_MISMATCH. See the OVERLAY_PAIRWISE_* family note.
	OverlayKindPairwiseWelchT OverlayKind = "OVERLAY_PAIRWISE_WELCH_T"

	// OverlayKindPanelIndexVsRef is the COMPOSE-host multi-reference
	// dual-shape ratio index — indexes EVERY target slot against the
	// SHARED reference slot and emits ONE OverlayLayer per target. The
	// chassis treats the spec as a panel container: every emitted layer
	// shares the reference slot's row/col coord space (matrix host) or
	// group key set (series host) so renderers can lay the panel on a
	// single co-ordinate canvas. Second multi-reference COMPOSE-only kind
	// in the catalog (sibling: OVERLAY_PROP_Z_PANEL)
	// and the first kind to emit MULTIPLE OverlayLayer entries from a
	// single ComposeOverlaySpec — the chassis dispatch widens to
	// `[]types.OverlayLayer` per spec via the multi-layer handler
	// surface added alongside this kind.
	//
	// Output layout (one layer per target):
	//
	//	layers[i].Name  = "<spec.Name>__<spec.Targets[i]>"
	//	layers[i].Kind  = OVERLAY_PANEL_INDEX_VS_REF
	//	layers[i].Scope = spec.Scope
	//	layers[i].Payload mirrors the reference slot's host shape
	//	  - MATRIX host: RowKeys / ColumnKeys cloned from the reference
	//	    matrix (the schema-match + key-alignment gates guarantee every
	//	    target shares the same coord space, so the reference is the
	//	    canonical anchor — mirrors the single-target INDEX_VS_REF /
	//	    PROP_Z_PANEL precedent).
	//	  - SERIES host: SeriesPayload whose Entries match the target's
	//	    Response.Data row order element-for-element (modulo missing-
	//	    ref drops).
	//
	// Spec.Name fallback: when `spec.Name == ""` the layer name template
	// degenerates to `"OVERLAY_PANEL_INDEX_VS_REF__<target_label>"` so
	// renderers can address every panel target by a stable handle even
	// against an unnamed authoring shape (mirrors the
	// `composeOverlayLayerName` fallback rule on the rest of the
	// COMPOSE catalog).
	//
	// Math: each emitted layer's per-coordinate value is mathematically
	// equivalent to OVERLAY_INDEX_VS_REF for the same (reference,
	// target[i]) pair — the handler reuses the single-target
	// `applyIndexVsRef` math arm verbatim, then renames the resulting
	// layer per the template above. This guarantees per-target byte-
	// identity with the single-pair OVERLAY_INDEX_VS_REF output for the
	// same slots.
	//
	// Cap enforcement — `OverlayOptions.MaxPanelTargets`: panel
	// combinatorics scale O(N) per cell (one independent ratio per
	// target) so the cap is informational rather than asymptotic — but
	// the catalog standardises on the same cap surface
	// OVERLAY_PROP_Z_PANEL uses so renderers can budget panel-layout
	// state against a single knob. Default 16 when `Options` is nil or
	// `Options.MaxPanelTargets == 0`. `len(spec.Targets) >
	// MaxPanelTargets` fires `PULSE_OVERLAY_PANEL_TARGETS_OVER_CAP` at
	// handler entry with `{kind, observed, cap}` Details.
	//
	// Layer slice order: spec order then target order — layers[i]
	// corresponds to spec.Targets[i], so renderers can address the
	// emitted panel by target offset without any auxiliary index map.
	// Stable across re-runs of the same spec.
	//
	// Shared coord space: the schema-match and key-alignment
	// gates already enforce coord-space identity across every
	// (reference, target) pair; the handler relies on that invariant
	// rather than re-validating per emission. A divergence at any pair
	// fails the chassis-side gate BEFORE the handler dispatches so the
	// emitted panel always shares one coord space.
	//
	// Streamable. Per `types/overlay_streamability.go` the row is `true`
	// — each emitted layer reuses the INDEX_VS_REF arithmetic (a
	// fold-only handler) so the per-target SERIES emission is fold-only
	// and the MATRIX emission rides through the slot barrier identically
	// to its single-target sibling. Mirrors the
	// `OVERLAY_INDEX_VS_REF` dual-shape streamability convention.
	OverlayKindPanelIndexVsRef OverlayKind = "OVERLAY_PANEL_INDEX_VS_REF"

	// OverlayKindTCell is the COMPOSE-host per-cell Welch t-test
	// against the reference slot's matching cell. CELL scope over a
	// MATRIX (crosstab) host with MATRIX payload — each cell's value is
	// the two-sided p-value as a float64. Each cell is treated as a
	// sample mean (see Inputs below).
	// The Welch t-test reuses the same Welch-Satterthwaite degrees-of-
	// freedom recurrence that backs `TEST_T` two-sample (see
	// `internal/processing/test_t.go`):
	//
	//	se      = sqrt(var_target/n_target + var_ref/n_ref)
	//	t       = (target_cell - ref_cell) / se
	//	df      = (var_target/n_target + var_ref/n_ref)^2 /
	//	          ( (var_target/n_target)^2 / (n_target-1)
	//	          + (var_ref/n_ref)^2     / (n_ref-1)     )
	//	p_value = studentTTwoSidedP(t, df)
	//
	// Reuses the `studentTTwoSidedP` helper backing `TEST_T` so the
	// overlay and the row-test surface produce identical p-values for
	// the same (mean, variance, n) triple.
	//
	// Inputs: a side whose value comes from components (AGG_WELFORD,
	// or a crosstab cell whose components carry mean and variance)
	// reads its (mean, variance, n) there. A scalar side REQUIRES
	// `Params["variance_target"]` / `Params["variance_ref"]` and
	// `Params["sample_size_target"]` / `Params["sample_size_ref"]` (or the
	// symmetric `variance` / `sample_size`), each a finite number > 0;
	// there is no default — PULSE_OVERLAY_PARAM_MISSING on predict and
	// runtime (U46 E4-S16; it was var = 1.0, n = 2).
	//
	// Buffered. Same rationale as `OVERLAY_PROP_Z_CELL`.
	OverlayKindTCell OverlayKind = "OVERLAY_T_CELL"

	// OverlayKindZCell is the COMPOSE-host per-cell two-sample z-test on
	// the means against the reference slot's matching cell. CELL scope
	// over a MATRIX (crosstab) host with MATRIX payload — each cell's
	// value is the two-sided p-value as a float64. Each cell is treated
	// as a sample mean (see Inputs below).
	// The z-test reuses the same Welch-style standard-error recurrence
	// that backs `OVERLAY_T_CELL` and finalises against the standard
	// normal survival helper that backs `TEST_Z_TWO_SAMPLE` (see
	// `internal/processing/test_z.go`):
	//
	//	se      = sqrt(var_target/n_target + var_ref/n_ref)
	//	z       = (target_cell - ref_cell) / se
	//	p_value = 2 * (1 - Φ(|z|))
	//
	// Reuses the `standardNormalCDF` helper backing `TEST_Z_TWO_SAMPLE` so
	// the overlay and the row-test surface produce identical p-values for
	// the same (mean, variance, n) triple.
	//
	// Inputs: a side whose value comes from components (AGG_WELFORD,
	// or a crosstab cell whose components carry mean and variance)
	// reads its (mean, variance, n) there. A scalar side REQUIRES
	// `Params["variance_target"]` / `Params["variance_ref"]` and
	// `Params["sample_size_target"]` / `Params["sample_size_ref"]` (or the
	// symmetric `variance` / `sample_size`), each a finite number > 0;
	// there is no default — PULSE_OVERLAY_PARAM_MISSING on predict and
	// runtime (U46 E4-S16; it was var = 1.0, n = 2).
	//
	// Buffered. Same rationale as `OVERLAY_PROP_Z_CELL`.
	OverlayKindZCell OverlayKind = "OVERLAY_Z_CELL"

	// OverlayKindChiSqVsRef is the COMPOSE-host whole-matrix χ² test
	// against the reference slot's matrix. The two matrices are treated
	// as two independent contingency tables and the test answers "do
	// the target and reference distributions differ?" via the standard
	// two-sample χ² approach: target cells are observed; reference
	// cells (scaled to target N) are expected. SCALAR payload — the
	// layer carries a single p-value on `OverlayPayload.Scalar` plus an
	// `OverlaySummary{Statistic, PValue, Parameters{"df"}}` summary.
	//
	// Math:
	//
	//	target_N  = sum(target_cells)
	//	ref_N     = sum(ref_cells)
	//	expected  = ref_cell * (target_N / ref_N)  // ref distribution scaled to target N
	//	chisq     = Σ (target_cell - expected)² / expected
	//	df        = (target cells with expected > 0) - 1
	//	p_value   = chiSquareSurvival(chisq, df)
	//
	// Reuses the `chiSquareSurvival` helper backing `TEST_CHISQ` and the
	// MATRIX-host CHISQ family so the overlay and the row-test surface
	// produce identical p-values for the same contingency.
	//
	// Degenerate inputs (`target_N == 0`, `ref_N == 0`, every expected
	// = 0) emit a NaN statistic + NaN p-value with one
	// `PULSE_OVERLAY_REF_ZERO` warning. Low-expected-cell warning
	// follows the canonical χ² rule the rest of the CHISQ family uses
	// (any `expected < 5` → one `PULSE_OVERLAY_EXPECTED_LOW` warning).
	//
	// Buffered. Inferential overlays as a family stay buffered until a
	// streamable-test path is plumbed.
	OverlayKindChiSqVsRef OverlayKind = "OVERLAY_CHISQ_VS_REF"

	// OverlayKindTVsRef is the COMPOSE-host per-group Welch t-test
	// against the reference slot's matching group, against a SERIES host
	// (grouped Process result). GROUP scope over a SERIES host with
	// SERIES payload — one `SeriesEntry` per host group key in host
	// order, each carrying the p-value on `Summary.Statistic`. Series-
	// shape sibling of `OVERLAY_T_CELL` and twin to the SERIES
	// arm of `OVERLAY_INDEX_VS_REF` / `OVERLAY_DELTA_VS_REF`. Distinct
	// kind from `OVERLAY_T_CELL` because the host shape disambiguator
	// (series vs matrix) and the per-group dispatch differ — the
	// renderer surfaces this kind as a per-group inferential strip,
	// not a per-cell badge.
	//
	// Math (per host group `i`):
	//
	//	target_val = target_slot.SeriesValue(i)
	//	ref_val    = ref_slot.SeriesValue(i)
	//	var_target = Params["variance_target"]    (required on a scalar side)
	//	var_ref    = Params["variance_ref"]       (required on a scalar side)
	//	n_target   = Params["sample_size_target"] (required on a scalar side)
	//	n_ref      = Params["sample_size_ref"]    (required on a scalar side)
	//	se         = sqrt(var_target/n_target + var_ref/n_ref)
	//	t          = (target_val - ref_val) / se
	//	df         = (var_target/n_target + var_ref/n_ref)^2 /
	//	             ((var_target/n_target)^2/(n_target-1) +
	//	              (var_ref/n_ref)^2/(n_ref-1))
	//	p_value    = studentTTwoSidedP(t, df)
	//
	// Reuses the `studentTTwoSidedP` helper backing `TEST_T` so the
	// overlay and the row-test surface produce identical p-values for
	// the same (mean, variance, n) triple. Mirrors `OVERLAY_T_CELL`'s
	// inputs rule: an AGG_WELFORD group reads its slot's per-group
	// components; a scalar group requires the params above — no default
	// (PULSE_OVERLAY_PARAM_MISSING). Over crosstab slots the kind is
	// PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE.
	//
	// Missing reference rows (target row key not present in the
	// reference series) emit `PULSE_OVERLAY_REF_ZERO` with a
	// `ref_missing=true` Detail flag; the affected entry's Statistic is
	// NaN. Degenerate inputs (`se == 0`, n < 2) produce NaN p-values
	// with the same warning.
	//
	// Buffered. Inferential overlays as a family stay buffered until a
	// streamable-test path is plumbed (PRD §2 Non-Goals "Streaming
	// overlay path for inferential kinds"). Even though the SERIES
	// host carrying the Welch t arms may individually stream, the
	// inferential family is buffered as a matter of policy.
	OverlayKindTVsRef OverlayKind = "OVERLAY_T_VS_REF"

	// OverlayKindZVsRef is the COMPOSE-host per-group two-sample z-test on
	// the means against the reference slot's matching group, against a
	// SERIES host (grouped Process result). GROUP scope over a SERIES host
	// with SERIES payload — one `SeriesEntry` per host group key in host
	// order, each carrying the p-value on `Summary.Statistic`. Series-
	// shape sibling of `OVERLAY_Z_CELL` and twin to the SERIES
	// arm of `OVERLAY_T_VS_REF` — same fold-and-finalise shape, different
	// distribution (standard normal instead of Student's t). Distinct
	// kind from `OVERLAY_Z_CELL` because the host shape disambiguator
	// (series vs matrix) and the per-group dispatch differ — the
	// renderer surfaces this kind as a per-group inferential strip,
	// not a per-cell badge.
	//
	// Math (per host group `i`):
	//
	//	target_val = target_slot.SeriesValue(i)
	//	ref_val    = ref_slot.SeriesValue(i)
	//	var_target = Params["variance_target"]    (required on a scalar side)
	//	var_ref    = Params["variance_ref"]       (required on a scalar side)
	//	n_target   = Params["sample_size_target"] (required on a scalar side)
	//	n_ref      = Params["sample_size_ref"]    (required on a scalar side)
	//	se         = sqrt(var_target/n_target + var_ref/n_ref)
	//	z          = (target_val - ref_val) / se
	//	p_value    = 2 * (1 - Φ(|z|))
	//
	// Reuses the `standardNormalCDF` helper backing `TEST_Z_TWO_SAMPLE` so
	// the overlay and the row-test surface produce identical p-values for
	// the same (mean, variance, n) triple. Mirrors `OVERLAY_Z_CELL`'s
	// inputs rule: an AGG_WELFORD group reads its slot's per-group
	// components; a scalar group requires the params above — no default
	// (PULSE_OVERLAY_PARAM_MISSING). Over crosstab slots the kind is
	// PULSE_OVERLAY_REF_INCOMPATIBLE_WITH_SHAPE.
	//
	// Missing reference rows (target row key not present in the
	// reference series) emit `PULSE_OVERLAY_REF_ZERO` with a
	// `ref_missing=true` Detail flag; the affected entry's Statistic is
	// NaN. Degenerate inputs (`se == 0`, n < 2) produce NaN p-values
	// with the same warning.
	//
	// Buffered. Inferential overlays as a family stay buffered until a
	// streamable-test path is plumbed (PRD §2 Non-Goals "Streaming
	// overlay path for inferential kinds"). Even though the SERIES
	// host carrying the z arms may individually stream, the
	// inferential family is buffered as a matter of policy.
	OverlayKindZVsRef OverlayKind = "OVERLAY_Z_VS_REF"

	// OverlayKindRank is the COMPOSE-host per-cell rank of each target
	// cell within a configurable population per `Params["population"]`
	// (`"row" | "column" | "matrix"`; defaults to `"matrix"`). CELL
	// scope over a MATRIX (crosstab) host with MATRIX payload — each
	// cell's value is the 1-based rank (1 = largest) computed against
	// the population the spec selected.
	//
	// Population modes:
	//
	//   - `"row"`: rank within the cell's own row across all columns.
	//     Ties take the average rank.
	//   - `"column"`: rank within the cell's own column across all rows.
	//   - `"matrix"` (default): rank across every present cell of the
	//     target matrix.
	//
	// The reference slot is required to anchor the resolution + key-set
	// gates but the rank computation itself reads only
	// the target cells — the reference matrix's structural schema is
	// the alignment constraint; its values are not consumed by the rank
	// math. This intentional asymmetry keeps RANK orthogonal to the
	// ref-vs-target comparison family (INDEX / DELTA / PROP_Z / T /
	// CHISQ) while still reusing the same resolution + alignment
	// pipeline.
	//
	// Ties: equal cell values receive the average of their would-be
	// ranks (canonical "average" tie-breaking; matches the convention
	// scipy.stats.rankdata uses by default).
	//
	// Absent cells: a structurally absent target cell stays absent on
	// the overlay; it does NOT participate in the population's
	// denominator (mirrors the absent-cell policy of the rest of the
	// MATRIX-host overlay family). Ranks are computed over PRESENT
	// cells only.
	//
	// Buffered. Same rationale as the rest of the COMPOSE-host kinds.
	OverlayKindRank OverlayKind = "OVERLAY_RANK"
)