descriptor

type AggregationPredict struct {
	// Type echoes the aggregation type from the request slot, in the
	// canonical SCREAMING_SNAKE form (e.g. "AGG_MEDIAN").
	Type types.AggregationType `json:"type"`

	// Field echoes the field referenced by the request slot. Empty
	// when the slot was authored without a field (defaults may have
	// filled it; the resolved post-defaults clone is reflected here
	// when applicable).
	Field string `json:"field,omitempty"`

	// Label echoes the response-side label the caller assigned to the
	// slot (or the engine-default label rule fallback when empty).
	// Predict echoes the raw label only — label fallback synthesis is
	// the orchestrator's responsibility.
	Label string `json:"label,omitempty"`

	// ComponentSchema is the static schema for the operator the engine
	// will use at runtime, projected from the capabilities table
	// (capabilities_aggregators.go for built-ins; the embedder snapshot
	// for extensions). Empty Keys + empty Mergeability means the slot
	// references an extension operator that has not (yet) declared a
	// ComponentSchema — the universal-floor populator still attaches
	// {"n", "n_null"} at runtime.
	ComponentSchema ComponentSchema `json:"component_schema"`

	// BufferedComponents is true iff ComponentSchema.Mergeability is
	// descriptor.None. The flag advertises that the slot's Components
	// block will arrive only on the terminal buffered flush in a
	// streaming run; it does NOT flip the overall Streamable axis (the
	// data slice still streams). AGG_MEDIAN and AGG_PERCENTILE are the
	// canonical Nones today.
	BufferedComponents bool `json:"buffered_components,omitempty"`
}

type Alternative struct {
	// When describes the situation in plain words.
	When string `json:"when"`
	// Use names the better choice: a bare registered operator name
	// (e.g. "TEST_WELCH") or a "<kind>:<name>" feature spelling with
	// kind one of capability, operator, io_format or mcp_extra.
	Use string `json:"use"`
}

type Band struct {
	// Min is the inclusive lower bound; nil means unbounded below.
	Min *float64 `json:"min,omitempty"`
	// Max is the exclusive upper bound; nil means unbounded above.
	Max *float64 `json:"max,omitempty"`
	// Label names the band (e.g. "small", "moderate").
	Label string `json:"label"`
}

type CohortFieldType struct {
	Name                  string   `json:"name"`
	Categorical           bool     `json:"categorical"`
	ShardedCapable        bool     `json:"sharded_capable"`
	CompatibleAggregators []string `json:"compatible_aggregators,omitempty"`
	CompatibleAttributes  []string `json:"compatible_attributes,omitempty"`
	CompatibleFilterers   []string `json:"compatible_filterers,omitempty"`
	CompatibleGroupers    []string `json:"compatible_groupers,omitempty"`
	CompatibleWindows     []string `json:"compatible_windows,omitempty"`
	CompatibleFeatures    []string `json:"compatible_features,omitempty"`
}

type Command struct {
	Name        string `json:"name"`
	Description string `json:"description"`

	// Annotations carries the three per-command capability hints
	// (streamable / deterministic / expensive). Embedders use these to
	// decide whether to wrap a command in caching or invoke it directly.
	// Always populated for built-in commands.
	Annotations CommandAnnotations `json:"annotations"`
}

type CommandAnnotations struct {
	Streamable    bool `json:"streamable"`
	Deterministic bool `json:"deterministic"`
	Expensive     bool `json:"expensive"`
}

type ComponentKey struct {
	// Name is the snake_case key the operator emits into the runtime
	// map[string]any returned by MetaAggregator.Components.
	Name string `json:"name"`
	// Type is the human-readable kind name of the emitted value.
	Type string `json:"type"`
	// Description is a single-sentence prose description suitable for
	// manifest / predict / MCP surfaces.
	Description string `json:"description"`
	// Optional marks a key that is emitted only under a condition the
	// Description states — the weighted floor keys (sum_weights, n_eff,
	// n_weight_invalid) appear only on a weighted slot. Omitted (false)
	// for a key every run emits.
	Optional bool `json:"optional,omitempty"`
}

type ComponentSchema struct {
	// Keys enumerates the named operator-specific components, in
	// emission order. May be empty when only the universal floor
	// applies.
	Keys []ComponentKey `json:"keys,omitempty"`
	// Mergeability classifies how the components map folds across
	// streaming chunks. Required for every schema (no zero-value
	// default — embedders must declare intent explicitly).
	Mergeability ComponentsMergeability `json:"mergeability"`
}

type Components struct {
	Aggregators []Operator `json:"aggregators"`
	Attributes  []Operator `json:"attributes"`
	Filterers   []Operator `json:"filterers"`
	Groupers    []Operator `json:"groupers"`
	Windows     []Operator `json:"windows"`
	Features    []Operator `json:"features"`
}

type ComponentsMergeability = types.ComponentsMergeability

type ComponentsSchemasBlock struct {
	Aggregators map[string]ComponentSchema `json:"aggregators,omitempty"`
	Groupers    map[string]ComponentSchema `json:"groupers,omitempty"`
	Filterers   map[string]ComponentSchema `json:"filterers,omitempty"`
	Matrices    map[string]ComponentSchema `json:"matrices,omitempty"`
}

type CrosstabCapability struct {
	// Name is the canonical entry identifier ("crosstab").
	Name string `json:"name"`

	// NormalizeModes lists every valid CrosstabSpec.Normalize value,
	// sorted alphabetically.
	NormalizeModes []string `json:"normalize_modes"`

	// Shapes lists every valid CrosstabSpec.Shape value, sorted
	// alphabetically.
	Shapes []string `json:"shapes"`

	// SummableAggregators is the alphabetized list of aggregator names
	// whose margin equals the sum of cells. v1 recomputes every margin
	// from raw rows for correctness; the classification is exposed so
	// callers can reason about future fast-path optimizations.
	SummableAggregators []string `json:"summable_aggregators"`
	// MeanReducibleAggregators lists aggregators whose margin is
	// derivable when each cell also carries its count.
	MeanReducibleAggregators []string `json:"mean_reducible_aggregators"`
	// IndependentAggregators lists aggregators that maintain their own
	// margin accumulator — the margin is neither a sum of cells nor a
	// re-scan (distinct_count, distinct_sum). Both crosstab paths feed
	// every record into independent row / column / grand accumulators,
	// so the margin is exact after one pass.
	IndependentAggregators []string `json:"independent_aggregators"`
	// RecomputeAggregators lists aggregators whose margin cannot be
	// derived from cells and must be recomputed over the raw filter-
	// passing rows.
	RecomputeAggregators []string `json:"recompute_aggregators"`

	// StreamingExceptions documents the only request shape that may
	// stream through the standard grouped path: shape=long, no
	// margins, no normalization. Intended for LLM-side reasoning.
	StreamingExceptions []string `json:"streaming_exceptions"`

	// RejectionRules names the structural failures the validator
	// emits. Intended for LLM-side autocomplete; not a strict schema.
	RejectionRules []string `json:"rejection_rules"`

	// SupportsNormalizeLevel reports whether the engine honors
	// CrosstabSpec.NormalizeLevel — the depth-index selector that
	// picks a parent grouper as the 100% denominator on nested row /
	// column axes. Always true in v1; carried so clients can detect
	// the feature without inferring it from CLI version.
	SupportsNormalizeLevel bool `json:"supports_normalize_level"`

	// NormalizeLevelRules names the rejection rules specific to the
	// NormalizeLevel slot. Intended for LLM-side autocomplete.
	NormalizeLevelRules []string `json:"normalize_level_rules"`

	// SupportsNormalizeWithin reports whether the engine honors
	// CrosstabSpec.NormalizeWithin — the cross-axis partition
	// selector that fixes a prefix of the OPPOSITE axis (columns
	// when normalize=row, rows when normalize=column) inside the
	// 100% denominator. Composes independently with NormalizeLevel.
	SupportsNormalizeWithin bool `json:"supports_normalize_within"`

	// NormalizeWithinRules names the rejection rules specific to the
	// NormalizeWithin slot.
	NormalizeWithinRules []string `json:"normalize_within_rules"`

	// SupportsMarginAggregations reports whether the engine honors
	// CrosstabSpec.MarginAggregations — the auxiliary aggregations
	// evaluated into the row / column / grand margin accumulators only
	// and never into a cell. The canonical use is a respondent base
	// riding alongside a weighted metric without a second scan.
	SupportsMarginAggregations bool `json:"supports_margin_aggregations"`

	// MarginAggregationRules names the rejection rules specific to the
	// MarginAggregations slot, plus the advisory that fires when the
	// section emits no margin to carry the auxiliary figures.
	MarginAggregationRules []string `json:"margin_aggregation_rules"`

	// MapValuedCellAggregators is the alphabetized list of aggregator
	// names whose Crosstab Cell output is map-valued (rich payload
	// per cell, e.g. AGG_SET_FREQUENCY's per-label row counts). These
	// aggregators emit map[string]int into MatrixCell.Value and the
	// long-shape cell rows; normalize modes (row / column / total) are
	// incompatible because dividing one map by another is undefined.
	// Derived from types.AggregationType.MapValued() at build time.
	MapValuedCellAggregators []string `json:"map_valued_cell_aggregators"`
}

type DefaultApplied struct {
	Path     []string `json:"path"`
	Field    string   `json:"field"`
	Type     string   `json:"type"`
	Category string   `json:"category"`
	Reason   string   `json:"reason"`
}

type DictionaryInfo struct {
	TotalEntries int      `json:"total_entries"`
	Truncated    bool     `json:"truncated"`
	Values       []string `json:"values"`
}

type DistributionMeta struct {
	// Name is the distribution kind identifier (e.g. "lognormal").
	Name string `json:"name"`

	// Description is a one-sentence prose summary.
	Description string `json:"description"`

	// AppliesTo lists the FieldSpec types the distribution can drive.
	// Values are coarse families: "numeric", "categorical", "date",
	// "bool", "any".
	AppliesTo []string `json:"applies_to"`

	// Params lists the distribution-specific parameters.
	Params []Param `json:"params"`

	// Intents lists the intent-taxonomy IDs (Manifest.Intents) the
	// distribution serves, sorted. Omitted when it declares no purpose.
	Intents []string `json:"intents,omitempty"`
}

type Domain string

type Envelope struct {
	FormatVersion string           `json:"format_version"`
	Data          any              `json:"data"`
	Request       any              `json:"request,omitempty"`
	Errors        []*EnvelopeEntry `json:"errors"`
	Warnings      []*EnvelopeEntry `json:"warnings"`
}

type EnvelopeEntry struct {
	Code    string         `json:"code"`
	Message string         `json:"message"`
	Details map[string]any `json:"details,omitempty"`
}

type ExportCapability struct {
	// Formats enumerates every format the export dispatcher supports,
	// sorted alphabetically by Name for deterministic golden output.
	// One entry per format. Empty slice never appears — Pulse always
	// ships at least the canonical seven adapters.
	Formats []ExportFormatCapability `json:"formats"`
}

type ExportFormatCapability struct {
	// Name is the canonical format identifier matching the
	// io.Format constants (csv / tsv / ndjson / jsonarray /
	// parquet / arrow / excel). Stable across format-version 1.0;
	// new formats land additively.
	Name string `json:"name"`

	// OverlaySupport names the per-format overlay-embedding strategy
	// the export dispatcher follows when ExportJob.IncludeOverlays
	// resolves to true. See ExportFormatCapability godoc for the
	// canonical label vocabulary.
	OverlaySupport string `json:"overlay_support"`

	// TimeZone is what the format does with ExportJob.TimeZone (CLI
	// --tz) naming a non-UTC zone:
	//
	//   - "local_offset" — datetime cells render as RFC 3339 literals on
	//     the zone's wall clock with its numeric offset
	//     (2026-03-29T08:00:00+05:30), which re-import to the same
	//     instants. Arrow and Parquet carry datetimes as UTF8 strings,
	//     so they follow the text formats.
	//   - "refused" — the export stops with a coded error (spss: a .sav
	//     DATETIME is a naive wall-clock count with no offset slot).
	//
	// An absent or UTC-equivalent zone is byte-identical UTC output on
	// every format.
	TimeZone string `json:"time_zone"`
}

type ExprFunctionMeta struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Signature   string `json:"signature,omitempty"`
	Pure        bool   `json:"pure,omitempty"`
}

type ExtensionsManifest struct {
	Aggregators        []OperatorMeta     `json:"aggregators"`
	Attributes         []OperatorMeta     `json:"attributes"`
	Filterers          []OperatorMeta     `json:"filterers"`
	Groupers           []OperatorMeta     `json:"groupers"`
	Windows            []OperatorMeta     `json:"windows"`
	Features           []OperatorMeta     `json:"features"`
	Tests              []OperatorMeta     `json:"tests"`
	SynthDistributions []OperatorMeta     `json:"synth_distributions"`
	ExprFunctions      []ExprFunctionMeta `json:"expr_functions"`
	LookupTables       []LookupTableMeta  `json:"lookup_tables"`
	LabelTables        []LabelTableMeta   `json:"label_tables"`
	RangeTables        []RangeTableMeta   `json:"range_tables"`
}

type FacetCapability struct {
	// Name is the canonical entry identifier ("facet_schema").
	Name string `json:"name"`

	// SupportsDiscrete reports whether per-value count summaries are
	// available for categorical / boolean / geo fields.
	SupportsDiscrete bool `json:"supports_discrete"`

	// SupportsNumeric reports whether streaming statistics
	// (count, sum, min, max, mean, stddev) are produced for numeric
	// fields.
	SupportsNumeric bool `json:"supports_numeric"`

	// SupportsPercentiles reports whether NumericPercentiles are
	// computed via a buffered second-stage sort.
	SupportsPercentiles bool `json:"supports_percentiles"`

	// SupportsHistogram reports whether IncludeHistogram +
	// HistogramRange + HistogramBins are honoured.
	SupportsHistogram bool `json:"supports_histogram"`

	// SupportsAdditive reports whether AdditiveFields contribution
	// counts are computed.
	SupportsAdditive bool `json:"supports_additive"`

	// SupportsOverlays reports whether FacetRequest.Overlays is
	// honoured. When true, the SupportedOverlayKinds slice enumerates
	// the FACET-host overlay catalog kinds the endpoint dispatches.
	// Four FACET-host kinds wire into FacetSchema's buffered exit:
	// OVERLAY_INDEX_VS_POP / OVERLAY_ZSCORE_VS_POP / OVERLAY_CHISQ_VS_POP
	// / OVERLAY_KS_VS_POP.
	SupportsOverlays bool `json:"supports_overlays,omitempty"`

	// SupportedOverlayKinds enumerates the FACET-host overlay kinds the
	// endpoint dispatches. Populated only when SupportsOverlays is true;
	// each entry is a canonical OverlayKind constant string. Stable
	// alphabetical order so LLM clients see a deterministic enum.
	SupportedOverlayKinds []string `json:"supported_overlay_kinds,omitempty"`

	// StreamableConditions lists the human-readable rules that govern
	// which requests run in a single pass vs. force the buffered
	// secondary sort. The order is stable and intended for LLM-side
	// reasoning, not strict parsing.
	StreamableConditions []string `json:"streamable_conditions"`
}

type FieldKind string

type FiltererPredict struct {
	// Type echoes the filterer type from the request slot, in the
	// canonical SCREAMING_SNAKE form (e.g. "FILTER_RANGE").
	Type types.FiltererType `json:"type"`

	// Field echoes the field referenced by the request slot. Empty
	// when the slot was authored without a field (FILTER_EXPRESSION
	// reads any record field through its expression body).
	Field string `json:"field,omitempty"`

	// ComponentSchema is the static schema for the filterer the engine
	// will use at runtime, projected from the capabilities table
	// (capabilities_filterers.go). Empty Keys + empty Mergeability
	// means the slot references an extension filterer that has not
	// (yet) declared a ComponentSchema — the universal-floor populator
	// still attaches {"n_in", "n_out", "n_null_input"} at runtime.
	ComponentSchema ComponentSchema `json:"component_schema"`

	// BufferedComponents is true iff ComponentSchema.Mergeability is
	// descriptor.None. The flag advertises that the slot's Components
	// block will arrive only on the terminal buffered flush in a
	// streaming run; it does NOT flip the overall Streamable axis. In
	// v1 every built-in filterer is Mergeable so this flag is always
	// false; the surface exists for future per-filter specifics that
	// may downgrade individual entries.
	BufferedComponents bool `json:"buffered_components,omitempty"`
}

type GroupPredict struct {
	// Type echoes the grouper type from the request slot, in the
	// canonical SCREAMING_SNAKE form (e.g. "GROUP_QUANTILE").
	Type types.GroupType `json:"type"`

	// Field echoes the field referenced by the request slot. Empty
	// when the slot was authored without a field (defaults may have
	// filled it; the resolved post-defaults clone is reflected here
	// when applicable).
	Field string `json:"field,omitempty"`

	// ComponentSchema is the static schema for the grouper the engine
	// will use at runtime, projected from the capabilities table
	// (capabilities_groupers.go). Empty Keys + empty Mergeability
	// means the slot references an extension grouper that has not
	// (yet) declared a ComponentSchema — the universal-floor
	// populator still attaches {"total_n", "n_null"} at runtime.
	ComponentSchema ComponentSchema `json:"component_schema"`

	// BufferedComponents is true iff ComponentSchema.Mergeability is
	// descriptor.None. The flag advertises that the slot's Components
	// block will arrive only on the terminal buffered flush in a
	// streaming run; it does NOT flip the overall Streamable axis (the
	// data slice still streams). GROUP_QUANTILE is the canonical
	// None today.
	BufferedComponents bool `json:"buffered_components,omitempty"`
}

type ImportCapability struct {
	// Formats enumerates every format the import dispatch supports,
	// sorted alphabetically by Name for deterministic golden output.
	// The native "pulse" format is excluded: it needs no tabular
	// reader and passes through untouched.
	Formats []ImportFormatCapability `json:"formats"`
}

type ImportFormatCapability struct {
	// Name is the canonical format identifier matching the io.Format
	// package constants (csv / tsv / ndjson / jsonarray / parquet /
	// arrow / excel / spss).
	Name string `json:"name"`

	// Extensions lists the lowercase file extensions (leading dot
	// included) that io.FormatFromPath resolves to this format, in the
	// dispatch's own order. Present so a planner can answer "what will
	// this path be detected as" without a round trip.
	Extensions []string `json:"extensions"`

	// SchemaSource is "authoritative" when the adapter implements
	// io.SchemaAwareReader and the source's own dictionary becomes the
	// .pulse schema, "inferred" when the shared sample-and-vote pass
	// decides the types. See ImportFormatCapability godoc.
	SchemaSource string `json:"schema_source"`

	// Export reports whether Pulse can also WRITE this format today.
	// False for import-only formats; cross-reference
	// ExportCapability.Formats for the writable set's overlay shapes.
	Export bool `json:"export"`
}

type InspectField struct {
	Name              string          `json:"name"`
	Type              string          `json:"type"`
	ByteOffset        int             `json:"byte_offset"`
	BitPosition       int             `json:"bit_position"`
	Description       string          `json:"description"`
	DescriptionSource string          `json:"description_source"`
	Categorical       bool            `json:"categorical"`
	Dictionary        *DictionaryInfo `json:"dictionary,omitempty"`
	// Precision is the decimal128 precision (1-38). Present only for
	// decimal128 / nullable_decimal128 fields.
	Precision *uint8 `json:"precision,omitempty"`
	// Scale is the decimal128 scale (0-precision). Present only for
	// decimal128 / nullable_decimal128 fields.
	Scale *uint8 `json:"scale,omitempty"`
	// Group is present only when the field is a parent-group member
	// (0x02): its value lives in that group's dictionary, not the row.
	// In a grouped cohort every field's ByteOffset is its LOGICAL-row
	// offset (the schema keeps the ungrouped descriptors), never a
	// physical one — Layout.PhysicalRecordStride is the on-disk row.
	Group *InspectFieldGroup `json:"group,omitempty"`
}

type InspectFieldGroup struct {
	Group int    `json:"group"`
	Key   bool   `json:"key"`
	Kind  string `json:"kind"`
}

type InspectGroup struct {
	Group           int      `json:"group"`
	Label           string   `json:"label"`
	Kind            string   `json:"kind"`
	Key             []string `json:"key,omitempty"`
	Members         []string `json:"members"`
	Fields          []string `json:"fields"`
	EntryCount      int      `json:"entry_count"`
	EntryWidth      int      `json:"entry_width"`
	DictionaryBytes int64    `json:"dictionary_bytes"`
	MemberRowBytes  int      `json:"member_row_bytes"`
	IndexWidth      int      `json:"index_width"`
	Ratio           float64  `json:"ratio"`
	BreakEvenRatio  float64  `json:"break_even_ratio"`
	RatioFloor      float64  `json:"ratio_floor"`
	ByteDelta       int64    `json:"byte_delta"`
	GrowsFile       bool     `json:"grows_file"`
	Verdict         string   `json:"verdict"`
}

type InspectLayout struct {
	PulseFormatVersion   int `json:"pulse_format_version"`
	PhysicalRecordStride int `json:"physical_record_stride"`
	LogicalRecordStride  int `json:"logical_record_stride"`
}

type InspectOptions struct {
	// FullDict disables dictionary truncation when true.
	FullDict bool
	// DictionaryLimit overrides the default truncation limit.
	// Zero means use DefaultDictionaryLimit.
	DictionaryLimit int
}

type InspectResult struct {
	FieldCount  int             `json:"field_count"`
	Fields      []*InspectField `json:"fields"`
	Shards      []ShardInfo     `json:"shards"`
	RecordCount int64           `json:"record_count"`
	// Layout describes the physical row of a 0x02 cohort. Omitted for 0x01.
	Layout *InspectLayout `json:"layout,omitempty"`
	// Groups reports each parent group in file order. Omitted when the
	// schema declares none.
	Groups []*InspectGroup `json:"groups,omitempty"`
	// SuggestedWeight names the row weight the cohort's own metadata
	// proposes — today the SPSS weighting variable recorded in the
	// cohort's SPSS metadata sidecar. A suggestion only: nothing ever
	// applies it. Omitted when there is no sidecar, the sidecar names
	// no weight, the variable is not a weight-capable column of this
	// schema, or the instance hides row weighting.
	SuggestedWeight *SuggestedWeight `json:"suggested_weight,omitempty"`
}

type Intent struct {
	// ID is the stable identifier operator purposes and examples cite
	// (e.g. "compare_groups").
	ID string `json:"id"`
	// Label is a short human-readable name.
	Label string `json:"label"`
	// Analytic is true for a question answered by operators; false for
	// an intent that routes to tooling instead (prepare, simulate,
	// lookup).
	Analytic bool `json:"analytic"`
	// Sounds lists example phrasings of the question.
	Sounds []string `json:"sounds"`
	// Shapes lists the alternative data shapes the intent applies to.
	Shapes []Shape `json:"shapes"`
}

type Interpretation struct {
	// Field is the normalised output path (e.g. "statistic",
	// "p_value", "details.effect_size.cohens_d").
	Field string `json:"field"`
	// Means says what the value measures, in plain words.
	Means string `json:"means,omitempty"`
	// Bands labels value ranges; Convention is required when set.
	Bands []Band `json:"bands,omitempty"`
	// Abs is true when Bands apply to the absolute value.
	Abs bool `json:"abs,omitempty"`
	// Convention attributes the Bands (e.g. "Cohen (1988)") — bands are
	// a labelled convention, never authoritative.
	Convention string `json:"convention,omitempty"`
	// Sign maps "+" / "-" to what each direction means.
	Sign map[string]string `json:"sign,omitempty"`
	// Caveats lists plain-language warnings about the value.
	Caveats []string `json:"caveats,omitempty"`
	// Shared names a shared rule set this field follows instead of
	// declaring its own (e.g. "p-value").
	Shared string `json:"shared,omitempty"`
}

type JoinCapability struct {
	// Name is the canonical identifier ("hash_join").
	Name string `json:"name"`

	// MaxJoinsPerRequest is the upper bound on Request.Joins length.
	// 1 today; lifts when multi-join chains land.
	MaxJoinsPerRequest int `json:"max_joins_per_request"`

	// Kinds lists supported JoinSpec.Kind values. "inner" today;
	// "left", "outer", "anti" land once the null-bitmap correctness
	// path is fully wired.
	Kinds []string `json:"kinds"`

	// SpillBytes reports the in-memory threshold beyond which the
	// build side would spill. Zero today (no spill — the build side
	// is always materialised in RAM); set when the spill path lands.
	SpillBytes int64 `json:"spill_bytes"`

	// SpillEnv names the environment variable that overrides the
	// spill threshold. Set when the spill path lands.
	SpillEnv string `json:"spill_env,omitempty"`

	// Limitations lists the v1 envelope notes for LLM clients.
	Limitations []string `json:"limitations"`
}

type LabelTableMeta struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	HasRowsData bool   `json:"has_rows_data"`
}

type Level string

type LimitFinding struct {
	Limit      string     `json:"limit"`
	Configured int64      `json:"configured"`
	Estimated  int64      `json:"estimated"`
	Grade      LimitGrade `json:"grade"`
}

type LimitGrade string

type LimitMeta struct {
	// Name is the snake_case limit key — the spelling of the feature
	// profile `limits` section, `pulse mcp --limit` and every
	// PULSE_LIMIT_* error's `limit` detail.
	Name string `json:"name"`
	// Value is the effective limit in Unit; -1 means no limit.
	Value int64 `json:"value"`
	// Default is the built-in default in Unit; -1 means no limit.
	Default int64 `json:"default"`
	// Unit is "nanoseconds" (request_timeout), "bytes"
	// (max_estimated_memory) or "count".
	Unit string `json:"unit"`
}

type LookupTableMeta struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	HasRowsData bool   `json:"has_rows_data"`
}

type MCPTool struct {
	// Name is the tool identifier (e.g. "pulse_predict").
	Name string `json:"name"`

	// Description mirrors the description string registered with the
	// MCP server.
	Description string `json:"description"`
}

type Manifest struct {
	FormatVersion string `json:"format_version"`
	// PulseVersion is the build version of the binary or library that
	// produced the manifest (buildinfo.Version: ldflags, then module
	// version, then "devel[+rev]"). It identifies the build, not the
	// payload contract — that is the envelope format_version.
	PulseVersion string `json:"pulse_version"`
	// TZDataVersion is the IANA tz database release embedded in the
	// build (e.g. "2026c"). Every zone name Pulse accepts and every
	// offset it applies comes from that copy alone — never the host's
	// zoneinfo — so two builds with the same value resolve every zone
	// identically. A build fact like PulseVersion: not part of
	// feature_set_digest.
	TZDataVersion string `json:"tzdata_version"`
	// FeatureSetDigest identifies the feature set the manifest
	// describes: "fs1:" + sha256hex over the instance's sorted enabled
	// feature names and its effective behaviour switches. Two manifests
	// with the same pulse_version and digest describe the same surface,
	// so, with LimitsDigest, it keys caches of self-description output.
	// Every manifest carries one; a profile-free instance (and the CLI)
	// carries the full-registry digest.
	FeatureSetDigest string `json:"feature_set_digest"`
	// LimitsDigest identifies the instance's effective resource limits
	// (Limits): "lim1:" + sha256hex over every limit's name and
	// effective value. It moves iff an effective limit changes and is
	// independent of FeatureSetDigest, so a manifest cache keys on
	// (pulse_version, feature_set_digest, limits_digest).
	LimitsDigest string    `json:"limits_digest"`
	Commands     []Command `json:"commands"`

	// Operations enumerates library-only entry points that do not back a
	// CLI leaf (today: filter_to_file, watch, process_stream). Each entry
	// carries the same CommandAnnotations as a CLI leaf so consumers can
	// reason uniformly about caching / streaming. The slice is sorted by
	// Name for determinism.
	Operations  []Command        `json:"operations"`
	Components  Components       `json:"components"`
	Tests       []TestMeta       `json:"tests"`
	PostTests   []TestMeta       `json:"post_tests"`
	Regressions []RegressionMeta `json:"regressions"`
	// Matrices lists the registered MAT_* matrix operators (empty when
	// the instance hides capability:matrices).
	Matrices           []MatrixMeta       `json:"matrices"`
	SynthDistributions []DistributionMeta `json:"synth_distributions"`
	// ErrorCodesCount is the total number of registered error codes.
	ErrorCodesCount int `json:"error_codes_count"`
	// ErrorDomains is the alphabetized list of distinct domain prefixes
	// (e.g. "CLI", "DATA", "ENCODING", "PROCESSING", "PULSE",
	// "SERVICE"). One entry per domain, six entries in v1.
	ErrorDomains []string `json:"error_domains"`
	// ErrorCodes is the alphabetized list of code identifiers.
	// Per-code Message + Fixup prose lives behind the
	// `pulse_errors_lookup` MCP tool / `pulse errors lookup CODE` CLI
	// leaf — depth-on-demand, not common-path.
	ErrorCodes        []string          `json:"error_codes"`
	MCPTools          []MCPTool         `json:"mcp_tools"`
	CohortTypes       []CohortFieldType `json:"cohort_types"`
	Skills            []SkillMeta       `json:"skills"`
	ExamplesCount     int               `json:"examples_count"`
	ExampleCategories []string          `json:"example_categories"`
	ExampleTags       []string          `json:"example_tags"`
	// Extensions enumerates embedder-registered operators + expression
	// state. Built-in operators continue to live in Components; this
	// block is the additive layer registered via
	// pulse.Options.Extensions. Empty slices on every field for a
	// host with no extensions.
	Extensions ExtensionsManifest `json:"extensions"`

	// Facet is the rich-facet endpoint capability descriptor. One
	// entry today (facet_schema); future variants land under a slice
	// when added.
	// Omitted (nil) when the instance does not offer capability:facet.
	Facet *FacetCapability `json:"facet,omitempty"`

	// ProcessChain is the source-rooted linear chain endpoint
	// capability descriptor (one entry today: process_chain).
	// Carries the mergeable-operator allowlist and rejection rules
	// so LLM clients can route between chain and per-stage fallback.
	// Omitted (nil) when the instance does not offer capability:process_chain.
	ProcessChain *ProcessChainCapability `json:"process_chain,omitempty"`

	// Join is the pushdown hash-join capability descriptor (one
	// entry today: hash_join). Carries the kind allowlist, spill
	// envelope, and v1 limitations.
	// Omitted (nil) when the instance does not offer capability:joins.
	Join *JoinCapability `json:"join,omitempty"`

	// Crosstab is the cross-tabulation endpoint capability
	// descriptor (Request.Crosstab). Carries the normalize / shape
	// allowlists plus the per-aggregator margin-reducibility
	// classification so LLM clients can decide which cell aggregator
	// will recompute its margin and which is summable.
	// Omitted (nil) when the instance does not offer capability:crosstab.
	Crosstab *CrosstabCapability `json:"crosstab,omitempty"`

	// Export is the cross-format export envelope. Carries one
	// ExportFormatCapability entry per format the export dispatcher
	// supports, declaring the per-format overlay-embedding shape
	// (sidecar / sheets / trailing_block / warn_and_skip) so LLM
	// planners can route Response.Overlays through ExportJob without
	// inspecting the io/ packages.
	// Omitted (nil) when the instance does not offer capability:export. Formats lists only the I/O formats the instance offers.
	Export *ExportCapability `json:"export,omitempty"`

	// Import is the cross-format import envelope — the read-side peer
	// of Export. Carries one ImportFormatCapability per format
	// io.NewReader factory accepts, declaring the file extensions that
	// resolve to it, whether its .pulse schema comes from the source's
	// own dictionary ("authoritative") or from the shared inference
	// pass ("inferred"), and whether the same format can also be
	// written. Read and write surfaces are NOT symmetric — SPSS is
	// import-only — so a planner must consult both blocks rather than
	// assuming one implies the other.
	// Omitted (nil) when the instance does not offer capability:import. Formats lists only the I/O formats the instance offers.
	Import *ImportCapability `json:"import,omitempty"`

	// Matrix is the matrix-slot capability descriptor
	// (Request.Vectors + Request.Matrices): encodings, matrix kinds,
	// missing modes, the merge block size and the v1 limitations.
	// Omitted (nil) when the instance does not offer
	// capability:matrices.
	Matrix *MatrixCapability `json:"matrix,omitempty"`

	// Overlays enumerates the registered overlay catalog — one
	// OverlayCapability per types.AllOverlayKinds() entry. Each entry
	// declares the supported OverlayShape × OverlayScope × OverlayRef
	// kinds the kind accepts plus its Buffered flag (the inverse of
	// types.OverlayStreamable). LLM clients route between overlay
	// catalog lookup and per-spec validation without crawling the
	// type system. Sorted alphabetically by Kind via
	// OverlayCapabilities() so the golden manifest stays stable.
	Overlays []OverlayCapability `json:"overlays"`

	// ComponentsSchemas projects the per-operator components contract
	// across categories as a name-keyed map. Embedders rely on this
	// block to plan ResponseComponents.Components[] consumption without
	// iterating Components.* per category.
	ComponentsSchemas ComponentsSchemasBlock `json:"components_schemas"`

	// Intents lists the intent-taxonomy IDs, sorted — the closed set of
	// question kinds every entry's intents list draws from. IDs only:
	// the full Intent records (labels, phrasings, data shapes) are
	// fetched on demand. Static: the same list under every feature
	// profile.
	Intents []string `json:"intents"`

	// ReturnPresets lists the named `return` presets (full / standard /
	// minimal, in that order), each with the response paths it selects
	// EXPANDED against this instance: a path a hidden feature owns is
	// absent. Always present: `return` is a plain request slot, not a
	// feature.
	ReturnPresets []ReturnPresetMeta `json:"return_presets"`

	// Limits lists the instance's EFFECTIVE resource limits, one entry
	// per limit in declaration order (request_timeout, max_groups,
	// max_crosstab_cells, max_estimated_memory, max_matrix_dim,
	// max_compose_slots, max_chain_stages, max_join_build_rows). Always
	// present: an instance without Options.Limits, a profile `limits`
	// section or `pulse mcp --limit` reports the built-in defaults.
	// Limits are behaviour, not features — they never enter
	// feature_set_digest; LimitsDigest identifies them.
	Limits []LimitMeta `json:"limits"`
}

type MatrixCapability struct {
	// Name is the canonical identifier ("matrices").
	Name string `json:"name"`
	// Encodings lists the MatrixSpec.Encoding values.
	Encodings []string `json:"encodings"`
	// DefaultEncoding is the encoding an empty MatrixSpec.Encoding
	// takes.
	DefaultEncoding string `json:"default_encoding"`
	// Kinds lists the MatrixValues.Kind values.
	Kinds []string `json:"kinds"`
	// MissingModes lists the missing-data modes.
	MissingModes []string `json:"missing_modes"`
	// MergeBlockSize is the record count of one merge block: rows fold
	// into per-block partials combined by one fixed tree.
	MergeBlockSize int `json:"merge_block_size"`
	// Limitations lists the v1 envelope notes for LLM clients.
	Limitations []string `json:"limitations"`
}

type MatrixMeta struct {
	// Name is the operator identifier (MAT_COVARIANCE).
	Name string `json:"name"`

	// Description is a one-sentence prose summary for LLM-side
	// operator selection.
	Description string `json:"description"`

	// AcceptsTypes lists the schema field types valid as members
	// (packed_bool only under the vector's coerce "binary").
	AcceptsTypes []string `json:"accepts_types"`

	// Params lists the operator's params object keys.
	Params []Param `json:"params"`

	// OutputKeys names the MatrixResult parts the operator fills.
	OutputKeys MatrixOutputKeys `json:"output_keys"`

	// Streamable mirrors types.MatrixType.Streamable(): the result is
	// emitted at finalize (terminal flush on the streaming path).
	Streamable bool `json:"streamable"`

	// Mergeable mirrors types.MatrixType.Mergeable(): the operator's
	// state merges across DecodeWorkers / ShardWorkers partitions
	// through the blocked merge tree, bit-identical to serial.
	Mergeable bool `json:"mergeable"`

	// ComponentSchema declares the operator's
	// Response.Components.Matrices entry: the matrix floor
	// {n, n_null, n_listwise_dropped}, the optional pairwise and
	// weighted floor keys, then the operator's own keys. Mirrored under
	// Manifest.ComponentsSchemas.Matrices.
	ComponentSchema ComponentSchema `json:"component_schema"`

	// Intents lists the intent-taxonomy IDs (Manifest.Intents) the
	// operator answers, sorted. Omitted when it declares no purpose.
	Intents []string `json:"intents,omitempty"`

	// WeightKinds lists the weight kinds the operator computes a
	// weighted matrix under; omitted when it honours no weight and on an
	// instance that hides capability:weighting. See
	// Operator.WeightKinds.
	WeightKinds []types.WeightKind `json:"weight_kinds,omitempty"`
}

type MatrixOutputKeys struct {
	Primary   string   `json:"primary"`
	Auxiliary []string `json:"auxiliary,omitempty"`
	Vectors   []string `json:"vectors,omitempty"`
	Scalars   []string `json:"scalars,omitempty"`
}

type MatrixPredict struct {
	// Name is the result name (MatrixSpec.EffectiveName).
	Name string `json:"name"`
	// Type is the matrix operator.
	Type types.MatrixType `json:"type"`
	// Shape is [p, p]: rows × columns of every matrix in the result.
	Shape [2]int `json:"shape"`
	// AxisKeys are the member field names in axis order — the result's
	// row_keys and column_keys.
	AxisKeys []string `json:"axis_keys"`
	// Labels are the members' display labels in axis order when the
	// vector supplies them (the result's labels); omitted otherwise.
	Labels []string `json:"labels,omitempty"`
	// Missing is the missing-data mode, "listwise" or "pairwise".
	Missing string `json:"missing"`
	// Encoding is the effective Values layout.
	Encoding types.MatrixEncoding `json:"encoding"`
	// AccumulatorBytes estimates the payload bytes of one co-moment
	// state over the members (32 + 8·(p + p(p+1)/2) listwise,
	// 32 + 56·p(p+1)/2 pairwise). The run holds one per populated merge
	// block (Manifest.Matrix.merge_block_size rows) until finalize, so
	// its matrix state is this times its block count (grouped: times
	// its buckets too — EstimatedBytes).
	AccumulatorBytes int64 `json:"accumulator_bytes"`
	// BucketBasis says how EstimatedBuckets was derived from the
	// request and the schema: "ungrouped" (1), "dictionary" (the
	// Groups[0] field's dictionary size), "boolean" (2), "include"
	// (Group.Include's distinct reachable keys), "quantile_bins"
	// (GROUP_QUANTILE's bin count) or "unknown" (the keys depend on the
	// data — ranges, dates, numeric categories — and the three estimate
	// fields are omitted).
	BucketBasis string `json:"bucket_basis"`
	// EstimatedBuckets is the upper bound on the results this spec
	// emits — one per non-empty bucket of Groups[0]; a bucket no row
	// reaches is not emitted, so a run returns at most this many.
	EstimatedBuckets *int64 `json:"estimated_buckets,omitempty"`
	// EstimatedCells is EstimatedBuckets × p² — the primary cells the
	// spec's results carry in full encoding.
	EstimatedCells *int64 `json:"estimated_cells,omitempty"`
	// EstimatedBytes is the run's co-moment state: merge blocks ×
	// EstimatedBuckets × AccumulatorBytes, the blocks being
	// ceil(records / merge_block_size) — per shard for an archive, whose
	// block numbering restarts per shard. An upper bound (a bucket holds
	// one state per block its rows touch). Omitted with the bucket count
	// unknown. It is the matrix term of the MaxEstimatedMemory estimate.
	EstimatedBytes *int64 `json:"estimated_bytes,omitempty"`
	// Streamable reports whether the operator folds row by row (its
	// result is emitted at finalize — terminal flush when streamed).
	// Request-level routing (groupers, two-pass attributes) is
	// PredictResult.Streamable.
	Streamable bool `json:"streamable"`
	// PairwisePSDRisk reports whether the result can come back not
	// positive semidefinite — pairwise MAT_COVARIANCE at p ≥ 2,
	// pairwise MAT_CORRELATION at p ≥ 3 — the only shapes the runtime
	// checks for PULSE_MATRIX_NOT_PSD. False guarantees the warning
	// never fires; true says it can, depending on the data.
	PairwisePSDRisk bool `json:"pairwise_psd_risk"`
}

type Ontology struct {
	Nodes []OntologyNode `json:"nodes"`
	Edges []OntologyEdge `json:"edges"`
}

type OntologyEdge struct {
	// From is the source node ID.
	From string `json:"from"`
	// To is the target node ID.
	To string `json:"to"`
	// Kind classifies the edge.
	Kind OntologyEdgeKind `json:"kind"`
}

type OntologyEdgeKind string

type OntologyNode struct {
	// ID is the stable node identifier (see the package spelling rule).
	ID string `json:"id"`
	// Kind classifies the node.
	Kind OntologyNodeKind `json:"kind"`
	// Name is the node's name in its own registry.
	Name string `json:"name"`
}

type OntologyNodeKind string

type Operator struct {
	// Name is the operator identifier (e.g. "AGG_PERCENTILE").
	Name string `json:"name"`

	// Category is the family this operator belongs to. One of:
	// "aggregator", "attribute", "filterer", "grouper", "window",
	// "feature".
	Category string `json:"category"`

	// Description is a one-sentence prose summary for LLM-side selection.
	Description string `json:"description"`

	// Params lists every parameter the operator reads from its Params
	// blob in a request. Required and optional are both listed.
	Params []Param `json:"params"`

	// AcceptsTypes lists the cohort field types this operator can be
	// applied to. Values are field type name strings (e.g. "f64",
	// "categorical_u16", "date"). Empty means "no field input".
	AcceptsTypes []string `json:"accepts_types"`

	// IgnoresField marks an operator that never reads the request slot's
	// own Field — it takes its inputs from Params instead (AGG_RATIO
	// reads Params.numerator_field / denominator_field).
	//
	// Without it, AcceptsTypes is ambiguous in the one way that matters:
	// a client cannot tell "every type is welcome here" from "this slot
	// is not read at all", and the full AcceptsTypes list reads as a
	// type claim about a slot the operator discards. When IgnoresField is
	// set, AcceptsTypes says only that no type is REFUSED (the request
	// wire form still requires a field name), and the operator's real
	// type constraints live on its Params entries, which carry
	// Type=="field" plus a FieldFilter.
	//
	// The claim is held two ways: descriptor's
	// TestCapabilities_IgnoresFieldDeclarationsAreCoherent checks the
	// declaration shape, and processing's
	// TestAggregators_IgnoredFieldSlotIsReallyIgnored runs the operator
	// with different Field values and requires an identical result.
	IgnoresField bool `json:"ignores_field,omitempty"`

	// EmitsType is the field type produced for single-output operators.
	// Empty when the operator's emit type is conditional on input or
	// when it does not emit a typed column (e.g. an aggregator emits a
	// scalar).
	//
	// No execution path reads this: attribute outputs are float64 end to
	// end, window outputs land in a map[string]any and feature outputs in
	// feature.Output.Values. It is a claim MCP clients size destination
	// columns from, and the only thing that can contradict it is
	// processing.TestManifestEmitsTypeHoldsAtRuntime, which runs every
	// operator that declares one and checks the values it really emits
	// against the declared domain. A new declaration must arrive with a
	// probe there or that gate fails.
	EmitsType string `json:"emits_type,omitempty"`

	// EmitsTypeNote provides context when EmitsType is empty or
	// conditional (e.g. "matches input field type", "scalar float64").
	EmitsTypeNote string `json:"emits_type_note,omitempty"`

	// Streamable mirrors types.X.Streamable() for the operator's type.
	// Source of truth for the runtime gate.
	Streamable bool `json:"streamable"`

	// StreamableHint suggests the closest streaming-capable alternative
	// when Streamable is false (e.g. AGG_MEDIAN -> "Use AGG_AVERAGE for
	// streaming, or accept the buffered path."). Empty when Streamable
	// is true or no near-equivalent exists.
	StreamableHint string `json:"streamable_hint,omitempty"`

	// ComponentSchema declares the per-operator components contract
	// surfaced through the runtime ResponseComponents shell and the
	// MetaAggregator / MetaGrouper / MetaFilterer sibling interfaces.
	// The universal floor of {"n", "n_null"} is declared on every
	// aggregator entry so manifest consumers see a self-contained
	// schema without consulting orchestrator code; the operator-
	// specific keys are appended in emission order. Mergeability
	// classifies how the components map folds across streaming chunks.
	ComponentSchema ComponentSchema `json:"component_schema"`

	// Zone declares the operator's time-zone participation. "capable"
	// means the slot accepts a per-slot `tz` and resolves a zone through
	// the slot → request → Options.DefaultTimeZone → UTC precedence.
	// Empty (omitted) means the operator is not zone-capable and an
	// explicit `tz` on its slot is refused. Extension operators are
	// never zone-capable.
	Zone string `json:"zone,omitempty"`

	// WeightAware is true for an operator that computes a weighted
	// figure when a row weight (Request.Weight, a per-slot `weight`, or
	// Options.DefaultWeight) is in force on its slot, and omitted
	// otherwise: such an operator is skipped under an instance default
	// weight and refused under an explicit one (or, for an inferential
	// one, under any weight). Predict's per-slot `weights` status says
	// which happened.
	WeightAware bool `json:"weight_aware,omitempty"`

	// WeightKinds lists the weight kinds the operator computes a
	// weighted figure under: ["frequency","probability"] for an
	// operator weighted under both, ["frequency"] for a frequency-only
	// one (a probability weight in force on its slot is
	// PULSE_WEIGHT_UNSUPPORTED naming the kind). Omitted for an
	// operator that honours no weight, and on an instance that hides
	// capability:weighting.
	WeightKinds []types.WeightKind `json:"weight_kinds,omitempty"`

	// Intents lists the intent-taxonomy IDs (Manifest.Intents) the
	// operator answers, sorted. Omitted when the operator declares no
	// purpose.
	Intents []string `json:"intents,omitempty"`
}

type OperatorMeta struct {
	Name        string `json:"name"`
	Namespace   string `json:"namespace"`
	Description string `json:"description,omitempty"`
	Streamable  bool   `json:"streamable"`
	// FansOut is the grouper-only projection of
	// pulse.GrouperRegistration.FansOut — the embedder-side sibling of
	// types.GroupType.FansOut(), which knows built-in constants only.
	// True means one record can land in more than one bucket, so the
	// bucket counts SUM to more than the record total. Omitted (and
	// meaningless) for every other operator category; absent reads as
	// false, which is also the registration default.
	FansOut bool `json:"fans_out,omitempty"`
	// Mergeable is the aggregator / grouper projection of
	// pulse.AggregatorRegistration.Mergeable and
	// pulse.GrouperRegistration.Mergeable — the embedder-side sibling
	// of types.AggregationType.Mergeable() / types.GroupType.Mergeable().
	// True means partial states fold (extend.MergeableAggregator.Merge,
	// extend.MergeableGrouper.MergeState), so the parallel reducers
	// (ShardWorkers / DecodeWorkers) and ProcessChain accept the
	// operator. Omitted for every other category; absent reads as
	// false, which is also the registration default.
	Mergeable bool `json:"mergeable,omitempty"`
	// MarginReducibility is the aggregator-only projection of
	// pulse.AggregatorRegistration.MarginReducibility — the
	// embedder-side sibling of types.AggregationType.MarginReducibility()
	// ("summable", "mean_reducible", "independent" or "recompute").
	// A non-recompute class admits the operator as a fused crosstab
	// cell. Omitted when undeclared, which reads as "recompute": the
	// crosstab cell runs buffered.
	MarginReducibility string `json:"margin_reducibility,omitempty"`
	// WeightAware is the aggregator / attribute / test projection of
	// the registration's WeightAware declaration — the extension half
	// of the built-in Operator.WeightAware. True means the operator
	// reads the resolved row weight (extend.Record.Weight) and computes
	// a weighted figure; omitted otherwise.
	WeightAware bool                `json:"weight_aware,omitempty"`
	Accepts     []string            `json:"accepts,omitempty"`
	Emits       string              `json:"emits,omitempty"`
	Mode        string              `json:"mode,omitempty"`
	Tier        string              `json:"tier,omitempty"`
	Params      []OperatorParamMeta `json:"params,omitempty"`
	// Intents lists the intent-taxonomy IDs (Manifest.Intents) the
	// registration's purpose declares, sorted. Omitted when the
	// registration declares none.
	Intents []string `json:"intents,omitempty"`
}

type OperatorParamMeta struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	JSONType    string `json:"json_type"`
	Required    bool   `json:"required,omitempty"`
	Default     any    `json:"default,omitempty"`
}

type OverlayAppliedDescriptor struct {
	// Name echoes the renderer-facing label — either the spec's own
	// Name or a synthesised default (Kind + Scope + Ref) when empty.
	Name string `json:"name"`

	// Kind is the on-wire SCREAMING_SNAKE OverlayKind value.
	Kind types.OverlayKind `json:"kind"`

	// Scope echoes the spec's scope.
	Scope types.OverlayScope `json:"scope"`

	// Shape echoes the resolved OverlayShape the layer will carry —
	// derived from (Kind, Scope) via the capability catalog
	// (descriptor.overlayCapabilityFor). For single-shape kinds the
	// shape is unambiguous; for dual-shape kinds (OVERLAY_INDEX_VS_REF
	// / OVERLAY_DELTA_VS_REF / OVERLAY_PANEL_INDEX_VS_REF) the resolver
	// picks the shape matching the spec's scope (CELL ⇒ matrix, GROUP
	// ⇒ series); for whole-chain kinds (OVERLAY_INDEX_VS_STAGE /
	// OVERLAY_DELTA_VS_STAGE) the catalog declares every shape the
	// kind may emit (scalar / series / matrix) and the descriptor
	// leaves Shape empty — the realised shape depends on the target
	// stage's host shape, which Predict cannot determine without
	// inspecting the chain. Empty when the kind is unknown (the
	// validator surfaces PULSE_OVERLAY_KIND_UNKNOWN for the same
	// condition) or when no single shape can be resolved from the
	// spec at predict time.
	Shape types.OverlayShape `json:"shape,omitempty"`

	// Ref echoes the resolved OverlayRef discriminated union variant
	// as a renderer-friendly string. Format: "<family>:<discriminator>"
	// when the family carries an on-wire discriminator, "<family>" for
	// marker-only families, and "" for implicit-margin kinds (every
	// CHISQ_* / FISHER_EXACT_CELL / INDEX_VS_TOTAL / FORMULA) and the
	// COMPOSE-only catalog (Reference / Targets resolve via slot
	// labels, not via the OverlayRef discriminated union). Concrete
	// shapes:
	//
	//   - "margin:row" / "margin:column" / "margin:grand" — Ref.Margin
	//   - "sibling:<field>=<value>"                        — Ref.Sibling
	//   - "baseline_index:<position>"                      — Ref.BaselineIndex
	//   - "prior:<lag>"                                    — Ref.Prior
	//   - "rolling_mean"                                   — Ref.RollingMean (marker)
	//   - "yoy"                                            — Ref.YoY (marker)
	//   - "population:<cohort>"                            — Ref.Population
	//   - "stage:index:<index>" / "stage:name:<name>"      — Ref.Stage
	//   - "slot:<label>"                                   — Ref.Slot
	Ref string `json:"ref,omitempty"`

	// Streamable mirrors types.OverlayStreamable(kind). False for
	// the buffered crosstab catalog; streamable kinds surface the
	// per-kind decision uniformly.
	Streamable bool `json:"streamable"`
}

type OverlayCapability struct {
	// Kind is the on-wire SCREAMING_SNAKE OverlayKind value.
	Kind types.OverlayKind `json:"kind"`

	// Shapes lists every OverlayShape this kind may emit. Sorted
	// alphabetically for golden stability.
	Shapes []types.OverlayShape `json:"shapes"`

	// Scopes lists every OverlayScope this kind supports. Sorted
	// alphabetically for golden stability.
	Scopes []types.OverlayScope `json:"scopes"`

	// RefKinds lists the OverlayRef union pointer-field names this
	// kind consumes (e.g. "Margin"). Sorted alphabetically for golden
	// stability. These are Go field-name strings — the on-wire
	// discriminator (MarginAxis, sibling field, etc.) lives one level
	// deeper inside the chosen pointer.
	RefKinds []string `json:"ref_kinds"`

	// Buffered reports whether the orchestrator must materialise
	// records before evaluating this kind. Derived from
	// types.OverlayStreamable(kind) — Buffered is !streamable.
	Buffered bool `json:"buffered"`

	// Fields lists the OverlaySpec slot names beyond Kind / Scope /
	// Ref / Params that the kind's runtime honours. Sorted
	// alphabetically for golden stability. "level" and "within" are
	// honoured by the share / index / delta / zscore family (prefix-axis
	// denominator dispatch) while the χ² / Fisher inferential family
	// leaves the list empty (Level / Within must stay zero; non-zero
	// values fire PULSE_OVERLAY_LEVEL_OUT_OF_RANGE). SHARE_OF_TOTAL
	// declares the fields for renderer-facing parity with the rest of
	// the share family even though the grand-axis denominator makes the
	// slots inert at runtime — the predict gate still accepts in-range
	// values without behavior change.
	Fields []string `json:"fields,omitempty"`

	// Description is a short human-readable summary of what the kind
	// computes. Mirrors the prose in the matching skill.
	Description string `json:"description"`

	// Zone declares the kind's time-zone participation. "following"
	// means the kind carries no zone of its own and inherits the
	// resolved zone of its host grouper (OVERLAY_YOY follows its host
	// GROUP_DATE). Empty (omitted) means the kind is zone-agnostic.
	Zone string `json:"zone,omitempty"`

	// Intents lists the intent-taxonomy IDs (Manifest.Intents) the kind
	// answers, sorted. Omitted when the kind declares no purpose.
	Intents []string `json:"intents,omitempty"`

	// Inferential is true for a hypothesis-test kind — its numbers are
	// test statistics and p-values, read with the shared p-value rules
	// and subject to multiple-comparison caveats — and omitted for a
	// descriptive kind (shares, indices, deltas, z-scores). Declared per
	// kind, never inferred from the name.
	Inferential bool `json:"inferential,omitempty"`

	// WeightKinds lists the weight kinds the overlay kind honours a
	// weight under (["frequency","probability"] or ["frequency"]);
	// omitted for a descriptive kind (it reads the already-weighted host
	// payload), a refused kind, and on an instance that hides
	// capability:weighting. See Operator.WeightKinds.
	WeightKinds []types.WeightKind `json:"weight_kinds,omitempty"`
}

type PValueCount struct {
	// Total is the number of inferential p-values the request emits.
	Total int `json:"total"`
	// Uncorrected is how many of Total no correction reaches (their
	// slot's resolved method is none).
	Uncorrected int `json:"uncorrected"`
	// Basis is how the counts were derived: PValueBasisExact,
	// PValueBasisDictionary or PValueBasisLowerBound.
	Basis string `json:"basis"`
	// Threshold is MultiplicityTriggerThreshold.
	Threshold int `json:"threshold"`
}

type Param struct {
	// Name is the JSON key inside the operator's Params blob.
	Name string `json:"name"`

	// Type is the parameter's value type. One of:
	//   "float", "int", "string", "bool", "field", "enum", "list", "object".
	// "field" means the value names a cohort field; "enum" means the
	// value is one of EnumValues; "list" means a JSON array.
	Type string `json:"type"`

	// Required is true when the parameter must be supplied. Optional
	// parameters with a default carry Required=false and Default set.
	Required bool `json:"required"`

	// Default is the operator's default value when Required is false.
	// Omitted from JSON when nil.
	Default any `json:"default,omitempty"`

	// Description is a one-sentence prose explanation.
	Description string `json:"description"`

	// EnumValues lists the allowed values when Type=="enum".
	EnumValues []string `json:"enum_values,omitempty"`

	// FieldFilter constrains acceptable field types when Type=="field".
	// One of: "numeric", "categorical", "date", "any".
	FieldFilter string `json:"field_filter,omitempty"`
}

type PredictResult struct {
	Valid      bool               `json:"valid"`
	Request    *types.Request     `json:"request"`
	SchemaInfo *PredictSchemaInfo `json:"schema_info,omitempty"`
	// RecordCount reports the cumulative record total across all shards
	// when the cohort is a shard archive, and zero for single-file
	// cohorts (predict reads only headers/schemas, so single-file
	// counts are not computed by this no-execute path). The count is
	// derived by peeking each shard's own header.
	RecordCount int64 `json:"record_count"`
	// Shards mirrors InspectResult.Shards for archive-backed cohorts.
	// Empty (but non-nil) for single-file cohorts. Listed in zip
	// central-directory order.
	Shards []ShardInfo `json:"shards"`
	// Streamable reports whether ProcessStream / process --stream can
	// emit rows without buffering the entire result. False whenever the
	// request uses groups, attributes, windows, decimal fields, or any
	// non-streamable operator. Computed via per-type Streamable() methods
	// plus schema-aware checks.
	//
	// Streamability is a property of the request and the canonical
	// schema, not of the cohort shape — archive-backed cohorts inherit
	// the same streamability as a single-file cohort with the same
	// schema.
	Streamable bool `json:"streamable"`
	// StreamableReasons lists the gates that forced Streamable=false. Empty
	// when Streamable=true. Useful for users debugging why their request
	// is buffering.
	StreamableReasons []string `json:"streamable_reasons,omitempty"`
	// CrosstabFusable reports whether this instance would run the
	// request's crosstab on the fused in-decode arm (O(cells + margins)
	// memory, one decode pass) rather than the buffered arm that holds
	// every filter-passing record. Nil when the request carries no
	// crosstab spec. Computed from the same rule the engine dispatches
	// on (internal/crosstabfuse), on the defaults-resolved request, and
	// instance-aware: Options.DisableCrosstabFusion answers false with a
	// reason. Both arms produce identical output; only memory differs.
	//
	// The one fact predict cannot know is whether a keyable grouper's
	// factory accepts its params (e.g. a GROUP_DATE component the
	// runtime rejects): predict may then say true while the runtime
	// declines and the buffered path refuses the request with a coded
	// error — the request errors on either answer.
	CrosstabFusable *bool `json:"crosstab_fusable,omitempty"`
	// CrosstabFusionReasons lists, in rule order, every reason
	// CrosstabFusable is false — short stable prose. Empty when it is
	// true or nil.
	CrosstabFusionReasons []string `json:"crosstab_fusion_reasons,omitempty"`
	// Suggestions enumerates structured next-actions the caller can apply
	// to repair (or improve) the request. Suggestions fire on validation
	// issues — field-name typos, operator/type mismatches, date misuse,
	// missing required params — and on non-streamable but otherwise valid
	// requests (streamable-substitute hints). May be empty; never nil in
	// JSON output.
	Suggestions []Suggestion `json:"suggestions"`
	// DefaultsApplied lists every operator slot whose Type was inferred
	// from the named field's schema type. Predict computes this on a
	// clone of the request, so the echoed Request reflects exactly what
	// the engine would run; the DefaultsApplied list shows what would
	// have been filled in. Empty when no defaults fire; never nil in
	// JSON output.
	DefaultsApplied []DefaultApplied `json:"defaults_applied"`

	// Aggregations mirrors req.Aggregations in order, attaching the
	// per-slot ComponentSchema the engine will use at runtime (the
	// operator's `descriptor.ComponentSchema` projected from the
	// capabilities table — and via the manifest snapshot for
	// embedder-registered ops) plus the BufferedComponents flag.
	//
	// BufferedComponents is true iff the operator's
	// ComponentSchema.Mergeability is None — meaning the components
	// map cannot be reconstructed from per-chunk partials and the
	// orchestrator emits the Components block only on the terminal
	// buffered flush. The flag is a hint to streaming consumers; it
	// does NOT flip the overall Streamable axis (the data slice still
	// streams). Today the canonical None-mergeability operators are
	// AGG_MEDIAN and AGG_PERCENTILE.
	//
	// Empty when req.Aggregations is empty; never nil in JSON output.
	Aggregations []AggregationPredict `json:"aggregations"`

	// Groups mirrors req.Groups in order, attaching the per-slot
	// ComponentSchema the engine will use at runtime (the operator's
	// `descriptor.ComponentSchema` projected from the capabilities
	// table — same projection ComponentsSchemas.Groupers uses) plus
	// the BufferedComponents flag.
	//
	// BufferedComponents is true iff the operator's
	// ComponentSchema.Mergeability is None — meaning the components
	// map cannot be reconstructed from per-chunk partials and the
	// orchestrator emits the Components block only on the terminal
	// buffered flush. The flag is a hint to streaming consumers; it
	// does NOT flip the overall Streamable axis. Of the seven
	// registered groupers today, GROUP_QUANTILE is the canonical
	// None — quantile cutoffs need the sorted full input.
	//
	// Empty when req.Groups is empty; never nil in JSON output.
	Groups []GroupPredict `json:"groups"`

	// Filterers mirrors req.Filterers in order, attaching the per-slot
	// ComponentSchema the engine will use at runtime (the operator's
	// `descriptor.ComponentSchema` projected from the capabilities
	// table — same projection ComponentsSchemas.Filterers uses) plus
	// the BufferedComponents flag.
	//
	// Filterer components in v1 are uniform across every registered
	// filterer — the orchestrator emits the universal floor
	// {n_in, n_out, n_null_input} from the filter pass's per-record
	// counters. Mergeability is Mergeable for every entry today
	// (counters fold trivially via integer addition), so
	// BufferedComponents is always false. The flag is still surfaced
	// on the predict struct for symmetry with AggregationPredict and
	// GroupPredict so future per-filter specifics (e.g. n_below /
	// n_above for FILTER_RANGE) can downgrade the slot without
	// changing the predict shape.
	//
	// Empty when req.Filterers is empty; never nil in JSON output.
	Filterers []FiltererPredict `json:"filterers"`

	// OverlaysApplied lists every overlay spec the engine accepted, in
	// req.Overlays order. Each entry echoes the catalog identity (Name,
	// Kind, Scope) plus the streamability flag harvested from
	// types.OverlayStreamable(kind) so the caller can reason about the
	// buffered/streaming routing decision without re-parsing the spec.
	// Empty when req.Overlays is empty; never nil in JSON output.
	//
	// Per kind-catalog-v1 PRD §I-FR-I3 the predict surface is
	// `OverlaysApplied + OverlaysSchemaDivergence + OverlayCost`.
	// Predict emits one descriptor per spec in matching order across
	// the full overlay catalog; new kinds appended to
	// types.AllOverlayKinds() inherit the same per-spec emission
	// without re-opening this slot. The streamability-derived
	// dispatch routes streamable kinds to overlayCostStreamable and
	// buffered kinds to overlayCostBuffered; every kind in
	// types.AllOverlayKinds() carries a multiplier, and the
	// multi-ref scaling rule lives on the COMPOSE-host equivalent at
	// ComposeValidationResult.OverlayCost since Targets / MaxPanelTargets
	// only exist on ComposeOverlaySpec.
	OverlaysApplied []OverlayAppliedDescriptor `json:"overlays_applied"`

	// OverlaysSchemaDivergence lists every (left, right) overlay-spec
	// slot pair that produced incompatible result-schema shapes. Empty
	// for the Request-only Predict surface — divergence detection lives
	// on the Compose-host validator (ValidateCompose) — but the field is
	// present so consumers can rely on the shape today. Per PRD §I-FR-I3
	// the placeholder is honoured as "this slot is reserved and shipped
	// empty".
	OverlaysSchemaDivergence []SlotPair `json:"overlays_schema_divergence"`

	// OverlayCost maps each overlay-spec Name to a coarse cost score
	// the routing layer can consult before execution. The score is a
	// rough record-count multiplier per overlay slot — streamable kinds
	// fold inside the existing streaming pass (one extra accumulator per
	// record) and carry overlayCostStreamable; buffered kinds force a
	// post-host re-traversal of the materialised payload and carry
	// overlayCostBuffered. Per kind-catalog-v1 PRD §I-FR-I3 the value is
	// intentionally coarse — callers budgeting cost across slots sum the
	// map values; renderers showing a "this overlay will buffer the
	// host" warning branch on >= overlayCostBuffered. The map key is
	// the overlay spec's Name when set, and the synthesised default
	// (Kind + Scope + Ref) when empty — matching the Name field on
	// OverlayAppliedDescriptor below. Empty when req.Overlays is empty;
	// never nil in JSON output.
	OverlayCost map[string]float64 `json:"overlay_cost"`

	// TimeZones lists the resolved zone of every zone-capable slot
	// (GROUP_DATE, GROUP_DATE_RANGES, FILTER_DATE_RANGES, ATTR_DATE_PART,
	// FEAT_DATE_FEATURES — crosstab axes included) in request order:
	// filterers, features, attributes, groups, crosstab rows, crosstab
	// columns. Resolution is slot `tz` → Request.TimeZone →
	// Options.DefaultTimeZone → UTC, computed by the same function the
	// runtime validates with. Empty when no zone-capable slot is present;
	// never nil in JSON output.
	TimeZones []ResolvedZone `json:"time_zones"`

	// Weights lists how a row weight resolves on every weight-bearing
	// slot (aggregations, the crosstab cell and margin aggregations,
	// tests, post-tests, regressions, attributes, overlays) in that
	// order. Resolution is slot `weight` → Request.Weight →
	// Options.DefaultWeight → none, computed by the same function the
	// runtime validates with. Omitted when the request, its slots and
	// the instance name no weight at all, so an unweighted request's
	// predict output is unchanged.
	Weights []ResolvedWeight `json:"weights,omitempty"`

	// SuggestedWeight echoes inspect's suggested_weight as DATA (never
	// a warning, so strict mode is unaffected) when no slot resolves a
	// weight field. Never applied. Omitted when there is nothing to
	// suggest, a weight resolves, or the instance hides row weighting.
	SuggestedWeight *SuggestedWeight `json:"suggested_weight,omitempty"`

	// PValues counts the inferential p-values the request would emit —
	// one per test and post-test (the Tukey HSD post-test excluded: its
	// p-values are already corrected) plus every p-value an inferential
	// overlay layer carries — and how many of them no multiple-comparison
	// correction reaches. It is trigger data for suggesting a
	// `multiplicity` block, never an advisory: compare Uncorrected with
	// Threshold. Omitted when the request emits no p-value, when its
	// multiplicity blocks are refused, or when the instance hides the
	// multiple-comparison capability.
	PValues *PValueCount `json:"p_values,omitempty"`

	// ResolvedVectors maps each Request.Vectors name to its resolved
	// member list in axis order — literal `fields` entries in the
	// caller's order, glob and `pattern` expansions in schema order —
	// computed by the same resolver the runtime refuses with, against
	// the schema the request executes over. Omitted when the request
	// defines no vector or a vector is refused (the refusal is the
	// predict error).
	ResolvedVectors map[string][]string `json:"resolved_vectors,omitempty"`

	// Matrices mirrors req.Matrices in order once every spec resolves:
	// each matrix's shape, axis, missing mode, estimated accumulator
	// size, streamability and pairwise PSD risk, computed by the same
	// resolver and rules the runtime runs. Omitted when the request
	// carries no matrix or a spec is refused (the refusal is the
	// predict error).
	Matrices []MatrixPredict `json:"matrices,omitempty"`

	// Sizes estimates each top-level Response section the request
	// produces, unshaped and under the effective `return` plan, in
	// Response key order — reported on every request, with or without
	// a `return` block (no effective block: shaped equals full). A
	// section whose size depends on data predict cannot see (a grouper
	// with data-dependent keys, a join's column set, a single file's
	// row-level output with no record count) is omitted; a section the
	// request does not produce is omitted. Omitted entirely when the
	// `return` block is refused. Guidance only — never a byte-accurate
	// figure.
	Sizes []ResponseSectionSize `json:"sizes,omitempty"`

	// LimitFindings lists every instance resource limit (pulse.Limits)
	// the request's predictable figures exceed, in limit-declaration
	// order. A Certain finding is an exact figure the runtime will see —
	// predict adds the PULSE_LIMIT_EXCEEDED error the process pre-flight
	// raises and Valid is false. A Possible finding is an upper bound: a
	// warning only, Valid is untouched. Omitted when nothing exceeds a
	// limit.
	LimitFindings []LimitFinding `json:"limit_findings,omitempty"`

	// Return is the resolved `return` plan — the expanded selection the
	// runtime will apply, computed by the same resolver it calls.
	// Omitted when the request carries no `return` block or the block is
	// refused (the refusal is the predict error).
	Return *ReturnPlan `json:"return,omitempty"`
}

type PredictSchemaInfo struct {
	FieldCount int      `json:"field_count"`
	Fields     []string `json:"fields"`
}

type ProcessChainCapability struct {
	// Name is the canonical entry identifier ("process_chain").
	Name string `json:"name"`

	// MaxStages is the upper bound on Stages length. Zero indicates
	// no compile-time cap; runtime memory is bounded by the largest
	// intermediate response.Data slice.
	MaxStages int `json:"max_stages"`

	// MergeableAggregators lists the aggregator names that pass the
	// chain gate (mergeable + single-scalar emit). Alphabetically
	// sorted, deterministic across calls.
	MergeableAggregators []string `json:"mergeable_aggregators"`

	// MergeableGroupers lists the grouper names that pass the chain
	// gate.
	MergeableGroupers []string `json:"mergeable_groupers"`

	// RowLocalAttributes lists the attribute names that pass the
	// chain gate (row-local only).
	RowLocalAttributes []string `json:"row_local_attributes"`

	// RejectionRules names the operator categories the chain gate
	// rejects today. Intended for LLM-side reasoning and fallback
	// routing; not a strict schema.
	RejectionRules []string `json:"rejection_rules"`

	// OverlayKinds lists the whole-chain overlay catalog entries
	// accepted on ChainRequest.Overlays today. Alphabetically sorted.
	// Minimal additive surface kept for backward compatibility; the
	// richer per-kind sub-block at Overlays carries the full surface
	// (shapes / scopes / ref kinds / buffered / description).
	OverlayKinds []string `json:"overlay_kinds"`

	// Overlays enumerates the per-kind capability rows for every
	// whole-chain overlay the catalog declares. Sourced from
	// descriptor.overlayCapabilityFor() so the chain capability stays
	// byte-equal with the corresponding entries on Manifest.Overlays —
	// single source of truth for kind metadata. Sorted alphabetically by
	// Kind for golden stability. Each row carries:
	//
	//   - Kind        — the OverlayKind constant (SCREAMING_SNAKE).
	//   - Shapes      — every OverlayShape the kind may emit; whole-chain
	//                   kinds inherit the target stage's host shape so
	//                   the catalog declares MATRIX + SCALAR + SERIES.
	//   - Scopes      — the OverlayScope values the kind supports;
	//                   whole-chain kinds decorate the entire chain
	//                   result so Scopes == [total].
	//   - RefKinds    — the OverlayRef union pointer-field names the kind
	//                   consumes; the chain family consumes Stage.
	//   - Buffered    — !types.OverlayStreamable(kind); whole-chain kinds
	//                   stay buffered today (the streamability flag is
	//                   the inverse of the table in
	//                   types/overlay_streamability.go).
	//   - Description — short human-readable summary; mirrors the prose
	//                   in skills/overlay-system.md.
	Overlays []OverlayCapability `json:"overlays"`
}

type Purpose struct {
	// Plain is the one sentence a developer reads first.
	Plain string `json:"plain"`
	// Intents lists the intent IDs the operator answers; at least one.
	Intents []string `json:"intents"`
	// Questions lists natural-language questions the operator answers.
	Questions []string `json:"questions"`
	// UseCases maps an audience domain to a one-line use case.
	UseCases map[Domain]string `json:"use_cases,omitempty"`
	// NotFor lists the situations where another choice fits better.
	NotFor []Alternative `json:"not_for,omitempty"`
	// Assumptions lists the operator's assumptions as plain sentences.
	Assumptions []string `json:"assumptions,omitempty"`
	// Level grades the background the operator assumes.
	Level Level `json:"level,omitempty"`
	// Glossary lists the glossary term IDs the guidance relies on.
	Glossary []string `json:"glossary,omitempty"`
}

type RangeTableMeta struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	RangeCount  int    `json:"range_count"`
}

type RegressionMeta struct {
	// Name is the operator identifier (REG_OLS, REG_GLM,
	// REG_BAYES_LINEAR).
	Name string `json:"name"`

	// Description is a one-sentence prose summary for LLM-side
	// operator selection.
	Description string `json:"description"`

	// AcceptsTypes lists the schema field types valid as Target /
	// Predictors entries (numeric only in v1).
	AcceptsTypes []string `json:"accepts_types"`

	// EmitsTypeNote describes the structured output (RegressionResult)
	// since no scalar field type captures the fit summary.
	EmitsTypeNote string `json:"emits_type_note"`

	// Streamable mirrors types.RegressionType.Streamable(): true for
	// closed-form fits (REG_OLS, REG_BAYES_LINEAR), false for iterative
	// fits (REG_GLM). Spec-level modifiers (Resample, Selection) can
	// downgrade this further per request — see RegressionSpec.Streamable.
	Streamable bool `json:"streamable"`

	// StreamableHint flags the modifier downgrade rule so clients know
	// non-empty Resample / Selection forces the buffered path even on
	// streamable operators.
	StreamableHint string `json:"streamable_hint,omitempty"`

	// Params lists the per-operator parameter schema, including the
	// regularization, family, prior, resample, and selection knobs that
	// modify the underlying fit.
	Params []Param `json:"params"`

	// Modifiers names the spec-level orthogonal wrappers any regression
	// type supports. Each entry is a top-level RegressionSpec field
	// (Resample, Selection) plus its enum values; the field is
	// duplicated under Params for completeness but exposed at the top
	// level here so request authors can discover the composition story
	// without parsing the full param list.
	Modifiers []RegressionModifier `json:"modifiers,omitempty"`

	// Intents lists the intent-taxonomy IDs (Manifest.Intents) the
	// regression answers, sorted. Omitted when it declares no purpose.
	Intents []string `json:"intents,omitempty"`

	// WeightKinds lists the weight kinds the regression computes a
	// weighted fit under (["frequency","probability"] or ["frequency"]);
	// omitted when it honours no weight and on an instance that hides
	// capability:weighting. See Operator.WeightKinds.
	WeightKinds []types.WeightKind `json:"weight_kinds,omitempty"`
}

type RegressionModifier struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	EnumValues  []string `json:"enum_values"`
}

type ResolvedWeight struct {
	// Slot addresses the slot by its JSON path inside the request, e.g.
	// "aggregations[0]", "crosstab.cell",
	// "crosstab.margin_aggregations[1]", "tests[0]", "overlays[2]".
	Slot string `json:"slot"`

	// Operator is the slot's operator type (post smart-defaults), or
	// the overlay kind on an overlay slot.
	Operator string `json:"operator"`

	// Field is the resolved weight field; empty when Status is
	// "opted_out" or "none".
	Field string `json:"field,omitempty"`

	// Kind is the resolved weight kind ("probability" or "frequency",
	// the default spelled out); empty when Field is.
	Kind string `json:"kind,omitempty"`

	// Status is "applied", "skipped_not_weight_aware", "opted_out" or
	// "none".
	Status string `json:"status"`

	// Source names where the weight came from: "slot", "request",
	// "options" or "none".
	Source string `json:"source"`
}

type ResolvedZone struct {
	// Slot addresses the slot by its JSON path inside the request, e.g.
	// "groups[0]", "filterers[1]", "attributes[2]", "features[0]",
	// "crosstab.rows[0]", "crosstab.columns[1]".
	Slot string `json:"slot"`

	// Operator is the slot's operator type (post smart-defaults).
	Operator string `json:"operator"`

	// FieldType is the schema type of the slot's field ("datetime",
	// "date", ...), or empty when the field is not in the cohort schema
	// (a derived column).
	FieldType string `json:"field_type,omitempty"`

	// TZ is the zone name that applies to the slot, spelled as the
	// caller (or Options.DefaultTimeZone) spelled it; "UTC" when nothing
	// named one. Null when the field is not `datetime` and the zone was
	// inherited: a calendar date carries no instant, so an inherited
	// zone is not applied to it.
	TZ *string `json:"tz"`

	// Source names where TZ came from: "slot", "request", "options" or
	// "default". On a null TZ it names the level the skipped zone was
	// inherited from.
	Source string `json:"source"`
}

type ResponseSectionSize struct {
	// Section is the top-level Response key.
	Section string `json:"section"`
	// FullBytes estimates the section's wire bytes without the
	// selection.
	FullBytes int64 `json:"full_bytes"`
	// ShapedBytes estimates the section's wire bytes under the
	// effective `return` plan — the same model with every node the plan
	// drops removed; 0 when the plan excludes the section, FullBytes
	// when there is no effective plan. Never above FullBytes.
	ShapedBytes int64 `json:"shaped_bytes"`
	// Basis says how the section's row / cell count was derived:
	// "exact" (fixed by the request and schema — an ungrouped
	// aggregation's one row, an ungrouped matrix), "upper_bound" (a
	// schema bound the run never exceeds — grouper dictionary sizes
	// clamped to the record count, crosstab axis dictionaries, the
	// record count of a row-level output) or "heuristic" (a typical-size
	// guess — test details, regression terms, overlay payloads,
	// component operator maps, metadata).
	Basis string `json:"basis"`
}

type ReturnPlan struct {
	// Preset is the preset the block resolved from: full, standard,
	// minimal, or custom for explicit include / exclude without one.
	Preset string `json:"preset"`
	// Include is the selected paths (each with its whole subtree).
	Include []string `json:"include"`
	// Exclude is the removed paths; exclusion wins over inclusion.
	Exclude []string `json:"exclude"`
	// Keep is the nested `warnings` slots retained wherever their parent
	// object is emitted (unless excluded).
	Keep []string `json:"keep"`
	// Precision is the wire float significant-digit count; omitted when
	// unlimited.
	Precision int `json:"precision,omitempty"`
	// Identity reports that the plan changes nothing (the whole
	// response, unrounded).
	Identity bool `json:"identity"`
	// Digest identifies the resolved selection ("rp1:" + sha256 hex);
	// the preset name does not enter it.
	Digest string `json:"digest"`
	// UnresolvedIncludes lists the Open include paths (through a map key
	// or an open value) predict cannot resolve without data: at runtime
	// each may match nothing, which a buffered run reports as
	// PULSE_RETURN_PATH_UNMATCHED and a stream never reports. A
	// `data[*].<column>` include predict can match against the
	// request's known output columns is resolved and not listed.
	// Omitted when none.
	UnresolvedIncludes []string `json:"unresolved_includes,omitempty"`
}

type ReturnPresetMeta struct {
	// Name is the preset name (a types.ReturnPreset).
	Name string `json:"name"`
	// Paths is the selection the preset expands to on this instance, in
	// table order. Nested `warnings` slots are kept wherever their
	// parent is emitted and are not listed; full lists every visible
	// top-level key.
	Paths []string `json:"paths"`
}

type Role struct {
	// Name identifies the role within its shape (e.g. "outcome").
	Name string `json:"name"`
	// Kinds lists the field kinds that may fill the role; at least one.
	Kinds []FieldKind `json:"kinds"`
	// Min is the fewest fields the role takes; 0 marks it optional.
	Min int `json:"min"`
	// Max is the most fields the role takes, at least Min, or
	// RoleUnbounded for no upper bound.
	Max int `json:"max"`
}

type Shape struct {
	// Roles lists the shape's roles in authoring order.
	Roles []Role `json:"roles"`
}

type ShardInfo struct {
	Filename    string `json:"filename"`
	RecordCount int64  `json:"record_count"`
}

type SkillMeta struct {
	Name        string `json:"name"`
	Description string `json:"description"`
}

type SlotPair struct {
	// ReferenceLabel is the slot label the spec's Reference field
	// resolves to. May be empty when the failure is the reference
	// itself being unknown / unresolvable.
	ReferenceLabel string `json:"reference_label"`

	// TargetLabel is the slot label the spec's Targets[j] resolves
	// to. May be empty when the failure is on the Reference arm.
	TargetLabel string `json:"target_label"`

	// Reason is a stable, machine-readable identifier for the failure
	// class. See the SlotPair doc for the enum.
	Reason string `json:"reason"`
}

type SuggestedWeight struct {
	Field  string `json:"field"`
	Source string `json:"source"`
	Kind   string `json:"kind"`
}

type Suggestion struct {
	Path       []string `json:"path"`
	Reason     string   `json:"reason"`
	Current    any      `json:"current,omitempty"`
	Proposed   []any    `json:"proposed,omitempty"`
	Confidence float64  `json:"confidence"`
}

type Term struct {
	// ID is the stable identifier purposes and other terms cite
	// (e.g. "p-value").
	ID string `json:"id"`
	// Short is a one-sentence definition.
	Short string `json:"short"`
	// WhyCare says why the reader should care, in plain words.
	WhyCare string `json:"why_care,omitempty"`
	// SeeAlso lists related term IDs.
	SeeAlso []string `json:"see_also,omitempty"`
	// Jargon marks a term that must be glossary-linked wherever it
	// appears in plain-language guidance.
	Jargon bool `json:"jargon,omitempty"`
	// Forms lists the surface spellings that count as the term
	// appearing in prose (e.g. "p-value", "p value").
	Forms []string `json:"forms,omitempty"`
}

type TestMeta struct {
	// Name is the canonical entry identifier. For tier-1 this is the
	// TestType string (e.g. "TEST_ANOVA_WELCH"). For tier-2 this is the
	// TestType plus the variant suffix
	// (e.g. "TEST_ANOVA_WELCH/welch_one_way_post").
	Name string `json:"name"`

	// Family is the canonical TestType the variant belongs to
	// (e.g. "TEST_PEARSON_R"). Tier-1 entries always have
	// Family == Name. Tier-2 entries set Family to the underlying
	// TestType so clients can pair siblings.
	Family string `json:"family"`

	// Tier is 1 for row tests in Request.Tests, 2 for post tests in
	// Request.PostTests.
	Tier int `json:"tier"`

	// Variant is the algorithm flavour for tier-2 entries
	// (e.g. "welch_one_way_post"). Empty for tier-1 entries.
	Variant string `json:"variant,omitempty"`

	// Description is a one-sentence prose summary.
	Description string `json:"description"`

	// Streamable mirrors types.TestType.Streamable() for tier-1 entries.
	// Always false for tier-2 entries.
	Streamable bool `json:"streamable"`

	// Params lists the operator-specific parameters (alpha,
	// success_value, etc.).
	Params []Param `json:"params"`

	// Requires lists the top-level Test fields that must be set for the
	// test to run (e.g. "Field", "Field2", "SplitBy", "Rows", "Cols").
	// Drives request authoring directly.
	Requires []string `json:"requires,omitempty"`

	// Intents lists the intent-taxonomy IDs (Manifest.Intents) the test
	// family answers, sorted. Tier-2 entries carry their Family's.
	// Omitted when the family declares no purpose.
	Intents []string `json:"intents,omitempty"`

	// WeightKinds lists the weight kinds the tier-1 test computes a
	// weighted figure under (["frequency","probability"] or
	// ["frequency"]); omitted when it honours no weight, on every tier-2
	// entry (a post-test reads aggregated rows, never row weights), and
	// on an instance that hides capability:weighting. See
	// Operator.WeightKinds.
	WeightKinds []types.WeightKind `json:"weight_kinds,omitempty"`
}