synth

type CategoricalNumericCategoryFidelity struct {
	Category string `json:"category"`
	// SourceMean/SourceStd echo the captured
	// CategoricalNumericCategorySpec verbatim.
	SourceMean float64 `json:"source_mean"`
	SourceStd  float64 `json:"source_std"`
	// SyntheticMean/SyntheticStd are the realized conditional mean/std
	// over the _synthetic=true partition. MeanDelta/StdDelta are
	// abs(source-synthetic). All four are zero-valued and meaningless
	// when Error is set.
	SyntheticMean float64 `json:"synthetic_mean,omitempty"`
	SyntheticStd  float64 `json:"synthetic_std,omitempty"`
	MeanDelta     float64 `json:"mean_delta,omitempty"`
	StdDelta      float64 `json:"std_delta,omitempty"`
	// N is the number of _synthetic=true rows carrying this category
	// value with a non-null B — the realized category's own observation
	// count.
	N int `json:"n"`
	// Error is set instead of the Synthetic*/*Delta fields when the
	// synthetic partition realized no observation of this category at
	// all — mirrors PairwiseFidelity's own per-entry non-fatal contract.
	Error string `json:"error,omitempty"`
}

type CategoricalNumericCategorySpec struct {
	Category string  `json:"category"`
	Mean     float64 `json:"mean"`
	Std      float64 `json:"std"`
}

type CategoricalNumericCategoryStat struct {
	Category string  `json:"category"`
	Mean     float64 `json:"mean"`
	Std      float64 `json:"std"`
	// N is the number of non-null B observations conditioned on this
	// category — the input thinPairWarning checks against
	// MinPairObservations, exactly as NumericPairProfile.N and each
	// ContingencyCell.Count already do for the other two pair kinds.
	N int `json:"n"`
}

type CategoricalNumericPairFidelity struct {
	A          string                                `json:"a"`
	B          string                                `json:"b"`
	Categories []*CategoricalNumericCategoryFidelity `json:"categories,omitempty"`
}

type CategoricalNumericPairProfile struct {
	A          string                           `json:"a"` // categorical field name
	B          string                           `json:"b"` // numeric field name
	Categories []CategoricalNumericCategoryStat `json:"categories"`
	// N is the number of rows in the capture where both A and B were
	// simultaneously non-null, summed across every category (including
	// "other") — the pair's true co-occurrence count, mirroring
	// CategoricalPairProfile.N and NumericPairProfile.N.
	N int `json:"n"`
}

type CategoricalNumericPairSpec struct {
	A          string                           `json:"a"`
	B          string                           `json:"b"`
	Categories []CategoricalNumericCategorySpec `json:"categories"`
	// Min/Max clamp the conditional draw exactly as field B's own
	// unconditional normal reconstruction clamps to its observed range
	// (see SpecFromProfile). HasClamp distinguishes "clamp to [0,0]"
	// (rare, but a legitimate observed range for a constant field) from
	// "no clamp was declared" — a hand-authored from-schema spec that
	// omits Min/Max gets no clamping, exactly as normal's own optional
	// min/max params behave when absent.
	Min      float64 `json:"min,omitempty"`
	Max      float64 `json:"max,omitempty"`
	HasClamp bool    `json:"has_clamp,omitempty"`
}

type CategoricalPairCellSpec struct {
	AValue string `json:"a_value"`
	BValue string `json:"b_value"`
	Count  int    `json:"count"`
}

type CategoricalPairFidelity struct {
	A string `json:"a"`
	B string `json:"b"`
	// Delta is the total variation distance between the source and
	// synthetic joint-frequency tables (each normalized to proportions
	// before comparison), in [0, 1] — 0 when the two tables carry
	// identical support and proportions, 1 when they share none. Chosen
	// over a chi-square-style distance because it stays well-defined and
	// boundedly comparable to a fixed tolerance even when synthesis
	// realizes a cell the capture never saw (or vice versa) — a
	// chi-square statistic diverges when an expected cell is zero. Zero
	// valued and meaningless when Error is set.
	Delta float64 `json:"delta,omitempty"`
	// N is the number of _synthetic=true rows with both A and B
	// simultaneously non-null and dictionary-resolvable — the realized
	// pair's own co-occurrence count. CategoricalPairSpec carries no
	// source N of its own; the source total used to normalize its side
	// of the comparison is recovered by summing Cells' Count.
	N int `json:"n"`
	// Error is set instead of Delta when the synthetic partition
	// produced no co-occurring observation at all for this pair — mirrors
	// PairwiseFidelity's own per-pair non-fatal failure contract.
	Error string `json:"error,omitempty"`
}

type CategoricalPairProfile struct {
	A     string            `json:"a"`
	B     string            `json:"b"`
	Cells []ContingencyCell `json:"cells"`
	// N is the number of rows in the capture where both A and B were
	// simultaneously non-null — the pair's true co-occurrence count,
	// summed across every cell (the cells kept plus whatever is folded
	// into the "other"/"other" catch-all).
	N int `json:"n"`
}

type CategoricalPairSpec struct {
	A     string                    `json:"a"`
	B     string                    `json:"b"`
	Cells []CategoricalPairCellSpec `json:"cells"`
}

type CategoricalProfile struct {
	Cardinality int           `json:"cardinality"`
	Top         []CategoryHit `json:"top"`
}

type CategoryHit struct {
	Value  string  `json:"value"`
	Weight float64 `json:"weight"`
}

type ConditionalProfile struct {
	// NumericPairs lists the numeric-numeric pairs captured: the
	// row-aligned Pearson correlation and the count of rows where both
	// fields were simultaneously non-null (N) — the input
	// thinPairWarning checks against MinPairObservations. Capped at
	// ProfileOptions.CorrelationTopK strongest |rho| pairs, same
	// convention as Profile.Pairwise.
	NumericPairs []NumericPairProfile `json:"numeric_pairs,omitempty"`
	// CategoricalPairs lists the categorical-categorical pairs
	// captured: a bounded contingency table of observed
	// (a_value, b_value) co-occurrence counts per pair. See
	// CategoricalPairProfile for the two composed collapse points
	// (per-field top-K, then joint-cell ContingencyCellCap) that keep
	// this section bounded regardless of either field's cardinality.
	CategoricalPairs []CategoricalPairProfile `json:"categorical_pairs,omitempty"`
	// CategoricalNumericPairs lists the categorical-numeric pairs
	// captured: the numeric field's conditional mean/std broken out per
	// observed category of the categorical field. See
	// CategoricalNumericPairProfile for the single collapse point
	// (per-field top-K) that keeps this section bounded — no separate
	// joint-cardinality cap is needed here, unlike CategoricalPairs,
	// because a conditional numeric summary is one row per already-capped
	// category rather than a joint cell per pair of categories.
	CategoricalNumericPairs []CategoricalNumericPairProfile `json:"categorical_numeric_pairs,omitempty"`
	// SetCategoricalPairs lists the set-option x categorical pairs
	// captured (E5-S2): one bounded contingency table per (set field,
	// option, categorical field) combination, the set-option axis fixed
	// to the two-value {"selected","not_selected"} Bernoulli domain. See
	// SetCategoricalPairProfile.
	SetCategoricalPairs []SetCategoricalPairProfile `json:"set_categorical_pairs,omitempty"`
	// SetNumericPairs lists the set-option x numeric pairs captured
	// (E5-S2): one conditional mean/std pair (selected vs. not_selected)
	// per (set field, option, numeric field) combination. See
	// SetNumericPairProfile.
	SetNumericPairs []SetNumericPairProfile `json:"set_numeric_pairs,omitempty"`
	// SetSetPairs lists the option x option pairs captured between two
	// DIFFERENT set_* fields (E5-S2): a 2x2 contingency table per
	// (fieldA option, fieldB option) combination. Never captured between
	// two options of the same field. See SetSetPairProfile.
	SetSetPairs []SetSetPairProfile `json:"set_set_pairs,omitempty"`
}

type ConstraintSpec struct {
	Expr string `json:"expr"`
}

type ContingencyCell struct {
	AValue string `json:"a_value"`
	BValue string `json:"b_value"`
	Count  int    `json:"count"`
}

type CorrelationSpec struct {
	A           string  `json:"a"`
	B           string  `json:"b"`
	Correlation float64 `json:"correlation"`
}

type CorrelationStat struct {
	A   string  `json:"a"`
	B   string  `json:"b"`
	Rho float64 `json:"rho"`
}

type DateProfile struct {
	Start    string `json:"start"`
	End      string `json:"end"`
	Weekdays [7]int `json:"weekdays"`
}

type FidelityReport struct {
	SourceRows                 int                               `json:"source_rows"`
	SyntheticRows              int                               `json:"synthetic_rows"`
	Fields                     []*FieldFidelity                  `json:"fields,omitempty"`
	Pairwise                   []*PairwiseFidelity               `json:"pairwise,omitempty"`
	CategoricalPairwise        []*CategoricalPairFidelity        `json:"categorical_pairwise,omitempty"`
	CategoricalNumericPairwise []*CategoricalNumericPairFidelity `json:"categorical_numeric_pairwise,omitempty"`
	SetFields                  []*SetFieldFidelity               `json:"set_fields,omitempty"`
	SetCategoricalPairwise     []*SetCategoricalPairFidelity     `json:"set_categorical_pairwise,omitempty"`
	SetNumericPairwise         []*SetNumericPairFidelity         `json:"set_numeric_pairwise,omitempty"`
	SetSetPairwise             []*SetSetPairFidelity             `json:"set_set_pairwise,omitempty"`
	Warnings                   []string                          `json:"warnings,omitempty"`
}

type FieldFidelity struct {
	Field  string            `json:"field"`
	Test   types.TestType    `json:"test"`
	Result *types.TestResult `json:"result,omitempty"`
	Error  string            `json:"error,omitempty"`
}

type FieldProfile struct {
	Name        string              `json:"name"`
	Type        string              `json:"type"`
	Description string              `json:"description,omitempty"`
	NullRate    float64             `json:"null_rate"`
	Numeric     *NumericProfile     `json:"numeric,omitempty"`
	Categorical *CategoricalProfile `json:"categorical,omitempty"`
	Date        *DateProfile        `json:"date,omitempty"`
	// Set carries per-option marginal selection-frequency stats for a
	// set_* (multi-select bitmask) field (E5-S1). Populated instead of
	// Numeric/Categorical/Date — exactly one of the four is non-nil per
	// field, based on the field's schema type.
	Set *SetProfile `json:"set,omitempty"`
	// Precision/Scale carry decimal128 metadata so synth-from-profile can
	// reconstruct the original field shape.
	Precision uint8 `json:"precision,omitempty"`
	Scale     uint8 `json:"scale,omitempty"`
}

type FieldSpec struct {
	Name         string         `json:"name"`
	Type         string         `json:"type"`
	Nullable     bool           `json:"nullable,omitempty"`
	Description  string         `json:"description,omitempty"`
	Distribution string         `json:"distribution"`
	Params       map[string]any `json:"params,omitempty"`

	// Precision and Scale apply to decimal128.
	Precision uint8 `json:"precision,omitempty"`
	Scale     uint8 `json:"scale,omitempty"`

	// NullRate is the per-row probability that the field will be null.
	// Only meaningful when Nullable is true; ignored otherwise.
	NullRate float64 `json:"null_rate,omitempty"`
}

type NumericPairProfile struct {
	A   string  `json:"a"`
	B   string  `json:"b"`
	Rho float64 `json:"rho"`
	// N is the number of rows in the capture where both A and B were
	// simultaneously non-null — the pair's true co-occurrence count,
	// unlike Profile.Pairwise's Rho (computed from two independently
	// capped reservoirs that can drift out of alignment once either
	// field has nulls).
	N int `json:"n"`
}

type NumericProfile struct {
	Min  float64 `json:"min"`
	Max  float64 `json:"max"`
	Mean float64 `json:"mean"`
	Std  float64 `json:"std"`
	// Percentiles holds {p1, p5, p25, p50, p75, p95, p99} when
	// IncludeStats was on; nil otherwise.
	Percentiles []float64 `json:"percentiles,omitempty"`
	// Shape carries a fitted 2-component Gaussian mixture, captured
	// only when ProfileOptions.FitShape was set AND the mixture is a
	// genuine improvement over the plain Mean/Std normal above (BIC
	// selection — see fitNumericShape in shape.go). Additive +
	// omitempty: absent from every profile document captured without
	// --fit-shape (including every pre-existing document), and absent
	// for any numeric field whose observed distribution is already
	// close to normal — SpecFromProfile falls back to the ordinary
	// Mean/Std/Min/Max normal reconstruction whenever this is nil,
	// exactly as it always has.
	Shape *ShapeProfile `json:"shape,omitempty"`
}

type Options struct {
	// Seed makes the output deterministic. Same spec + same seed must
	// produce a byte-identical .pulse file.
	Seed int64

	// SourceCohort activates the tagged top-up path (AugmentFromProfile)
	// when non-empty: real rows from this cohort are copied into the
	// output tagged _synthetic=false, spec.RowCount new rows are
	// generated and tagged _synthetic=true, and the source is never
	// opened for write. Leaving it empty (the default) reproduces
	// today's behavior exactly — a plain synthesis with no tag column,
	// used by synth from-schema and any caller building a Spec directly.
	SourceCohort string

	// FidelityReportPath activates the post-generation fidelity report
	// (`synth from-profile --fidelity-report`) when non-empty: after
	// generation completes, AugmentFromProfile drives TEST_KS (numeric
	// fields, SplitBy=_synthetic) / TEST_CHISQ (categorical fields,
	// contingency against _synthetic) against the tagged output cohort
	// and writes the resulting FidelityReport JSON document to this
	// path. Only meaningful alongside SourceCohort — the plain Synth
	// path (SourceCohort empty) has no _synthetic partition to compare
	// against and ignores this field entirely.
	FidelityReportPath string

	// FidelityWarnings, when non-empty, are copied verbatim onto the
	// written FidelityReport's own Warnings slot — the mechanism that
	// surfaces thin-pair warnings (e.g. Profile.Warnings from a
	// `profile create --conditional` capture) beside the pairwise
	// correlation deltas they qualify in the same document (FR-18),
	// rather than requiring a caller to cross-reference the profile
	// file separately. This package has no Profile type of its own to
	// read Warnings from directly — the caller (internal/cli's `synth
	// from-profile`, or any programmatic caller building Options from a
	// Profile it already has in hand) is expected to populate this.
	// Ignored when FidelityReportPath is empty, exactly like every
	// other Fidelity* field.
	FidelityWarnings []string
}

type PairwiseFidelity struct {
	A            string  `json:"a"`
	B            string  `json:"b"`
	SourceRho    float64 `json:"source_rho"`
	SyntheticRho float64 `json:"synthetic_rho,omitempty"`
	// Delta is abs(SourceRho - SyntheticRho). Zero-valued and
	// meaningless when Error is set.
	Delta float64 `json:"delta,omitempty"`
	// N is the number of _synthetic=true rows with both A and B
	// simultaneously non-null — the realized pair's own co-occurrence
	// count, distinct from (and typically much larger than) the source
	// capture's own N.
	N int `json:"n"`
	// Error is set instead of SyntheticRho/Delta when the synthetic
	// partition could not produce a defined correlation for this pair
	// (fewer than two co-occurring non-null observations) — mirrors
	// FieldFidelity's own per-field failure contract: one pair's
	// failure never withholds the rest of the report.
	Error string `json:"error,omitempty"`
}

type Profile struct {
	RowCount int               `json:"row_count"`
	Fields   []FieldProfile    `json:"fields"`
	Pairwise []CorrelationStat `json:"pairwise,omitempty"`
	// Conditional carries joint-reconstruction structure captured only
	// when ProfileOptions.IncludeConditional was set. Additive and
	// omitempty: absent on every profile document captured without
	// --conditional, including every pre-existing one, and
	// SpecFromProfile treats a nil Conditional exactly as it always
	// has (falling back to Pairwise).
	Conditional *ConditionalProfile `json:"conditional,omitempty"`
	Warnings    []string            `json:"warnings,omitempty"`
	Meta        map[string]any      `json:"meta,omitempty"`
}

type ProfileOptions struct {
	// TopK is the number of top categorical values to capture per
	// categorical field. Defaults to 32 when zero.
	TopK int
	// IncludeStats turns on percentile / stdev / kurtosis collection.
	// When false, only mean / min / max / null-rate are recorded for
	// numeric fields. Defaults to true.
	IncludeStats bool
	// IncludeCorrelations enables pairwise Pearson correlation capture
	// between numeric fields. Off by default to keep profile size bounded.
	IncludeCorrelations bool
	// CorrelationTopK caps the number of strongest |rho| pairs retained.
	// Defaults to 16 when IncludeCorrelations or IncludeConditional is
	// true.
	CorrelationTopK int
	// IncludeConditional enables capture of the joint reconstruction
	// structure (`profile create --conditional`): for numeric-numeric
	// field pairs, a row-aligned correlation + observation count
	// (Profile.Conditional.NumericPairs) that SpecFromProfile uses to
	// drive the exact conditional-Gaussian reconstruction in
	// synth/copula.go, in place of the plain (and, for cohorts with
	// nulls, only approximately aligned) Pairwise correlation stats.
	// Off by default; the profile document's `conditional` key is
	// entirely absent (omitempty) when this is false, and every
	// pre-existing profile document — which has no such key — remains
	// valid SpecFromProfile input either way.
	IncludeConditional bool
	// SampleLimit caps the number of records ingested for the profile.
	// Zero = unlimited.
	SampleLimit int
	// FitShape enables shape-fitting for numeric fields
	// (`profile create --fit-shape`, E4-S2): instead of always
	// summarizing a numeric field as a single normal(mean, std),
	// attempt a 2-component Gaussian mixture fit and keep it — as
	// FieldProfile.Numeric.Shape — only when it is a genuine
	// improvement over the plain normal by BIC (see fitNumericShape in
	// shape.go for the full selection rule and its documented
	// limitations). Off by default; a field whose fit is not kept (not
	// enough data, or the source is already close to normal) carries no
	// Shape, and SpecFromProfile reconstructs it exactly as it always
	// has. Forces sample retention (as if IncludeStats were also set)
	// for numeric fields so there is something to fit against, even
	// when IncludeStats itself is false.
	FitShape bool
	// Seed drives the reservoir-sampling RNG used by
	// IncludeConditional's categorical-categorical contingency capture
	// (E7-S2) once the source cohort exceeds conditionalJointCap rows.
	// Zero (the default) is itself a valid, deterministic seed — same
	// as synth.Options.Seed's convention — so two profile runs against
	// the same source with the same Seed (including the unset zero
	// value) produce byte-identical captured output. It does not affect
	// any other capture path: every other section in this file is
	// either an exact online accumulation or a first-N reservoir with
	// no random draws.
	Seed int64
}

type Result struct {
	RowsGenerated int      `json:"rows_generated"`
	RowsRejected  int      `json:"rows_rejected"`
	OutputPath    string   `json:"output_path"`
	Warnings      []string `json:"warnings,omitempty"`

	// FidelityReportPath echoes Options.FidelityReportPath when a
	// fidelity report was written alongside the output cohort. Empty
	// when the flag was not set.
	FidelityReportPath string `json:"fidelity_report_path,omitempty"`
}

type SetCategoricalPairFidelity struct {
	Set         string  `json:"set"`
	Option      string  `json:"option"`
	Categorical string  `json:"categorical"`
	Delta       float64 `json:"delta,omitempty"`
	// N is the number of _synthetic=true rows with both the set field
	// and the categorical field simultaneously non-null — the realized
	// pair's own co-occurrence count.
	N int `json:"n"`
	// Error is set instead of Delta when the synthetic partition
	// produced no co-occurring observation at all for this pair —
	// mirrors CategoricalPairFidelity's own per-pair contract.
	Error string `json:"error,omitempty"`
}

type SetCategoricalPairProfile struct {
	Set         string            `json:"set"`
	Option      string            `json:"option"`
	Categorical string            `json:"categorical"`
	Cells       []ContingencyCell `json:"cells"`
	// N is the number of rows where both the set field and the
	// categorical field were simultaneously non-null — this option's
	// true co-occurrence count, mirroring CategoricalPairProfile.N.
	N int `json:"n"`
}

type SetCategoricalPairSpec struct {
	Set         string                    `json:"set"`
	Option      string                    `json:"option"`
	Categorical string                    `json:"categorical"`
	Cells       []CategoricalPairCellSpec `json:"cells"`
}

type SetFieldFidelity struct {
	Field   string               `json:"field"`
	Options []*SetOptionFidelity `json:"options,omitempty"`
}

type SetNumericPairFidelity struct {
	Set        string                                `json:"set"`
	Option     string                                `json:"option"`
	Numeric    string                                `json:"numeric"`
	Categories []*CategoricalNumericCategoryFidelity `json:"categories,omitempty"`
}

type SetNumericPairProfile struct {
	Set     string `json:"set"`
	Option  string `json:"option"`
	Numeric string `json:"numeric"`
	// Categories carries at most two entries, keyed "selected" /
	// "not_selected" — reuses CategoricalNumericCategoryStat verbatim
	// rather than a bespoke two-field struct, so a caller already
	// handling CategoricalNumericPairProfile.Categories needs no second
	// shape to learn.
	Categories []CategoricalNumericCategoryStat `json:"categories"`
	// N mirrors CategoricalNumericPairProfile.N: the total non-null
	// co-occurrence count summed across both categories.
	N int `json:"n"`
}

type SetNumericPairSpec struct {
	Set        string                           `json:"set"`
	Option     string                           `json:"option"`
	Numeric    string                           `json:"numeric"`
	Categories []CategoricalNumericCategorySpec `json:"categories"`
	Min        float64                          `json:"min,omitempty"`
	Max        float64                          `json:"max,omitempty"`
	HasClamp   bool                             `json:"has_clamp,omitempty"`
}

type SetOptionFidelity struct {
	Value string `json:"value"`
	// SourceFrequency/SyntheticFrequency are P(bit set) over each
	// partition's non-null rows of Field. Delta is
	// abs(SourceFrequency - SyntheticFrequency). SyntheticFrequency and
	// Delta are zero-valued and meaningless when Error is set.
	SourceFrequency    float64 `json:"source_frequency"`
	SyntheticFrequency float64 `json:"synthetic_frequency,omitempty"`
	Delta              float64 `json:"delta,omitempty"`
	// N is the number of _synthetic=true rows with a non-null Field —
	// the realized synthetic partition's own denominator for this
	// option's frequency, shared across every option of the same field.
	N int `json:"n"`
	// Error is set instead of SyntheticFrequency/Delta when the
	// synthetic partition has no non-null observation of Field at all —
	// mirrors every other Fidelity entry kind's non-fatal per-entry
	// contract.
	Error string `json:"error,omitempty"`
}

type SetOptionStat struct {
	Value string `json:"value"`
	// Count is the number of non-null rows with this option's bit set.
	Count int `json:"count"`
	// Frequency is Count / SetProfile.N — P(bit set), the per-option
	// marginal Bernoulli rate.
	Frequency float64 `json:"frequency"`
}

type SetProfile struct {
	// N is the number of non-null rows Options' frequencies are computed
	// over — the same denominator FieldProfile.NullRate already implies,
	// surfaced here so a caller reading only the Set block can interpret
	// Count as a rate without cross-referencing NullRate.
	N int `json:"n"`
	// Options lists EVERY dictionary entry in bit/dictionary order (bit i
	// first) — NOT sorted by frequency like CategoricalProfile.Top — so
	// two profiles of the same schema are directly comparable
	// position-for-position regardless of which option happens to be
	// more popular.
	Options []SetOptionStat `json:"options"`
}

type SetSetPairFidelity struct {
	SetA    string  `json:"set_a"`
	OptionA string  `json:"option_a"`
	SetB    string  `json:"set_b"`
	OptionB string  `json:"option_b"`
	Delta   float64 `json:"delta,omitempty"`
	// N is the number of _synthetic=true rows with both set fields
	// simultaneously non-null — the realized pair's own co-occurrence
	// count.
	N int `json:"n"`
	// Error is set instead of Delta when the synthetic partition
	// produced no co-occurring observation at all for this pair.
	Error string `json:"error,omitempty"`
}

type SetSetPairProfile struct {
	SetA    string            `json:"set_a"`
	OptionA string            `json:"option_a"`
	SetB    string            `json:"set_b"`
	OptionB string            `json:"option_b"`
	Cells   []ContingencyCell `json:"cells"`
	// N is the number of rows where both fields were simultaneously
	// non-null — this option pair's true co-occurrence count.
	N int `json:"n"`
}

type SetSetPairSpec struct {
	SetA    string                    `json:"set_a"`
	OptionA string                    `json:"option_a"`
	SetB    string                    `json:"set_b"`
	OptionB string                    `json:"option_b"`
	Cells   []CategoricalPairCellSpec `json:"cells"`
}

type ShapeProfile struct {
	Means   []float64 `json:"means"`
	Stds    []float64 `json:"stds"`
	Weights []float64 `json:"weights"`
}

type Spec struct {
	// RowCount is the number of rows to generate. Required (>0).
	RowCount int `json:"row_count"`

	// Fields declares each column with its type and distribution.
	Fields []FieldSpec `json:"fields"`

	// Constraints, if non-empty, are evaluated per row by the expression
	// evaluator. Rows that fail any constraint are rejected and re-drawn.
	Constraints []ConstraintSpec `json:"constraints,omitempty"`

	// MaxRejectionRate caps the fraction of rejected rows during
	// constraint-driven rejection sampling. Defaults to 0.5 if zero.
	MaxRejectionRate float64 `json:"max_rejection_rate,omitempty"`

	// Correlations lists optional pairwise correlations to induce via
	// Gaussian copula post-processing. Each entry references two numeric
	// fields by name with a target Pearson correlation in [-1, 1]. Only
	// numeric fields can participate.
	Correlations []CorrelationSpec `json:"correlations,omitempty"`

	// CategoricalPairs lists optional categorical-categorical joint
	// structure to reproduce during generation: for each pair, field B
	// is resampled conditioned on field A's independently-drawn value
	// using the captured contingency cells, instead of being drawn from
	// its own unconditional marginal. Populated by SpecFromProfile from
	// ConditionalProfile.CategoricalPairs (`profile create --conditional`)
	// when present; absent (nil, the zero value) reproduces today's
	// independent-marginal behavior exactly — every pre-existing spec,
	// hand-authored or profile-derived, has no such key.
	CategoricalPairs []CategoricalPairSpec `json:"categorical_pairs,omitempty"`

	// CategoricalNumericPairs lists optional categorical-numeric
	// conditional structure to reproduce during generation: for each
	// pair, numeric field B is resampled from Normal(mean, std)
	// parameterized by categorical field A's drawn value, using the
	// captured per-category conditional mean/std, instead of being drawn
	// from its own unconditional normal. Populated by SpecFromProfile
	// from ConditionalProfile.CategoricalNumericPairs when present;
	// absent (nil) reproduces today's independent-marginal behavior
	// exactly.
	CategoricalNumericPairs []CategoricalNumericPairSpec `json:"categorical_numeric_pairs,omitempty"`

	// SetCategoricalPairs lists optional set-option x categorical joint
	// structure to reproduce during generation (E5-S3): for each pair,
	// the set field's declared Option (bit) is resampled from
	// Bernoulli(P(selected | categorical field's drawn value)) using the
	// captured contingency cells, instead of the option's own
	// independent marginal frequency. Populated by SpecFromProfile from
	// ConditionalProfile.SetCategoricalPairs when present; absent (nil)
	// reproduces the independent per-option marginal behavior exactly.
	SetCategoricalPairs []SetCategoricalPairSpec `json:"set_categorical_pairs,omitempty"`

	// SetNumericPairs lists optional set-option x numeric joint
	// structure to reproduce during generation (E5-S3): for each pair,
	// numeric field B is resampled from Normal(mean, std) conditioned on
	// whether the set field's declared Option (bit) was independently
	// drawn selected, using the captured per-bucket conditional
	// mean/std. Populated by SpecFromProfile from
	// ConditionalProfile.SetNumericPairs when present; absent (nil)
	// reproduces today's independent-marginal behavior exactly.
	SetNumericPairs []SetNumericPairSpec `json:"set_numeric_pairs,omitempty"`

	// SetSetPairs lists optional option x option joint structure between
	// two DIFFERENT set_* fields to reproduce during generation (E5-S3):
	// for each pair, set B's declared OptionB (bit) is resampled from
	// Bernoulli(P(selected | set A's OptionA drawn state)) using the
	// captured 2x2 contingency cells. Populated by SpecFromProfile from
	// ConditionalProfile.SetSetPairs when present; absent (nil)
	// reproduces the independent per-option marginal behavior exactly.
	SetSetPairs []SetSetPairSpec `json:"set_set_pairs,omitempty"`
}

type TestRunner func(physicalSchema, presentedSchema *encoding.Schema, records []byte, test *types.Test) (*types.TestResult, error)