factory

type Batch struct {
	// Dir is the corpus testdata directory family files are written into.
	Dir string
	// Quota caps committed scenarios per run. §5.2: per-run quotas keep PRs
	// reviewable; the steady state is months of batches, not one dump.
	Quota int
	// contains filtered or unexported fields
}

type Candidate struct {
	Seed       uint64
	QueryIndex int
	ProjIndex  int
	Case       *rowdiff.Case
	Query      rowdiff.Query
	Projection []string
	// Nested marks a candidate derived by NestedCandidates: its case carries a
	// struct column and its projections name dotted paths. It selects the
	// generator version stamped into the emitted header, and it keeps the file
	// NAME disjoint from the flat family so the two can share a seed number.
	Nested        bool
	FeatureVector string
}

type CrossEngine interface {
	Rows(ctx context.Context, schemaTemplate string, setup []string, query string) ([][]any, error)
}

type Finding struct {
	Oracle    string   `json:"oracle"`
	Seed      uint64   `json:"seed"`
	Candidate string   `json:"candidate"`
	Detail    string   `json:"detail"`
	DDL       string   `json:"ddl"`
	Setup     string   `json:"setup"`
	Queries   []string `json:"queries"`
	Left      string   `json:"left"`
	Right     string   `json:"right"`
}

type Manifest struct {
	Date          string `json:"date"`
	Generator     string `json:"generator"`
	SeedStart     uint64 `json:"seed_start"`
	Seeds         uint64 `json:"seeds"`
	Quota         int    `json:"quota"`
	BlessingMode  string `json:"blessing_mode"`
	CandidatesGen int    `json:"candidates_generated"`
	CandidatesRun int    `json:"candidates_executed"`
	Blessed       int    `json:"blessed"`
	Committed     int    `json:"committed"`
	// DedupRejected counts blessed candidates dropped because their (feature
	// vector, plan shape) point was already covered. A high number is HEALTHY
	// — it is the frontier flattening — and a zero is the number to be
	// suspicious of, because it means the key is discriminating on something
	// that varies per candidate.
	DedupRejected int `json:"dedup_rejected"`
	// DedupPoints is the number of distinct points the committed corpus covers
	// after this batch.
	DedupPoints int `json:"dedup_points"`
	// NameCollisions counts blessed candidates whose file name was already
	// taken on disk. It is called out as its own field rather than left in the
	// skip ledger because it is the one skip class that means a committed
	// scenario was nearly destroyed: the file name and the dedup key are
	// independent, so a planner change moves the key (dedup misses) without
	// moving the name (the write would clobber). A non-zero value is a
	// statement about the ENGINE, not about the batch.
	NameCollisions int `json:"name_collisions"`
	// SkipsByReason is the counted-skip ledger. Every candidate that did not
	// become a test appears here under a reason class; a run whose skips do
	// not account for its candidates is a run with a silent drop in it.
	SkipsByReason map[string]int `json:"skips_by_reason"`
	// SkipSamples holds a few verbatim messages per reason class. A class with
	// a count and no example is a class nobody can triage: "second-plan infra
	// 28" is indistinguishable between a transport hiccup and the disabled-rule
	// option being accepted and ignored, and those are a shrug and an emergency.
	SkipSamples map[string][]string `json:"skip_samples"`
	Oracles     OracleStats         `json:"oracles"`
	Blessings   map[string]int      `json:"blessings"`
	// Exemptions names the structural-inapplicability families available to
	// this run, each with the pin establishing it and the oracle that would
	// retire it. A batch that blessed anything on fewer oracles than the rest
	// says so here, in the same document as the counts — an exemption a
	// reader has to go find in the source is one they will not.
	Exemptions []string `json:"exemptions"`
	// BlessedByFamily counts TLP-only blessings per exemption family, so the
	// SIZE of each weakening is visible next to its justification.
	BlessedByFamily map[string]int       `json:"blessed_by_family"`
	Findings        int                  `json:"findings"`
	Census          factorycorpus.Census `json:"census_after"`
}

type OracleStats struct {
	// TLPChecked counts candidates whose partition property was evaluated.
	TLPChecked int `json:"tlp_checked"`
	// TLPViolations counts partitions that did not reconstruct — each is a
	// finding, not a skip.
	TLPViolations int `json:"tlp_violations"`
	// SecondPlanKept counts query executions where the second plan genuinely
	// differed and the rows were compared.
	SecondPlanKept int `json:"second_plan_kept"`
	// SecondPlanSkipped counts executions where disabling the rule left the
	// plan unchanged, so there was no second plan to compare against. Counted,
	// never silent — and floored against SecondPlanKept at the run level,
	// because "every case skipped" is exactly what the option being accepted
	// and ignored would look like.
	SecondPlanSkipped int `json:"second_plan_skipped"`
	// SecondPlanViolations counts row disagreements between two plans for the
	// same query — the strongest planner-bug signal this harness has.
	SecondPlanViolations int `json:"second_plan_violations"`
	// CrossEngineKept / CrossEngineViolations count the Java leg.
	CrossEngineKept       int `json:"cross_engine_kept"`
	CrossEngineViolations int `json:"cross_engine_violations"`
	// TLPOnlyBlessed counts candidates blessed on TLP alone because the
	// second-plan oracle was STRUCTURALLY inapplicable to their shape. It is
	// reported so the size of the exemption is visible rather than inferred
	// from the difference between two other counters.
	TLPOnlyBlessed int `json:"tlp_only_blessed"`
}

type Outcome struct {
	Candidate Candidate
	Blessed   bool
	Header    factorycorpus.Header
	Scenario  *yamsql.Scenario
	Skip      string
	Findings  []*Finding
	Stats     OracleStats
	// InapplicableFamily names the structural-inapplicability family that
	// permitted a TLP-only blessing, or "" when every applicable oracle ran.
	InapplicableFamily string
}

type Runner struct {
	// DefaultConn plans with the full rule set.
	DefaultConn *sql.Conn
	// SecondPlanConn has secondPlanDisabledRule disabled, so the same query
	// takes a different access path.
	SecondPlanConn *sql.Conn
	// Java, when non-nil, blesses cross-engine.
	Java CrossEngine
	// Date is the batch date stamped into every header. It is an INPUT, never
	// read from the clock: §5.4 forbids wall-clock in the generation path, so
	// a committed file can be regenerated byte-identically.
	Date string
}

type Sweep struct {
	// SetupDB executes the schema DDL; it must already point at an existing
	// database path.
	SetupDB *sql.DB
	DBPath  string
	// ClusterFile is the path the per-schema query connections open.
	ClusterFile string
	// Java, when non-nil, adds the cross-engine oracle.
	Java CrossEngine
	// Date is stamped into every header.
	Date string
	// Filter, when non-nil, restricts the sweep to the candidates it accepts.
	// It exists for re-emission (the format migration regenerates exactly the
	// committed (seed, query, projection) triples): re-running a seed evaluates
	// every candidate it derives, and the ones the original batches
	// dedup-rejected must not be offered now, or a re-emission would grow the
	// corpus as a side effect of rewriting it.
	Filter func(Candidate) bool
	// Nested sweeps the NESTED candidate family instead of the flat one: same
	// seeds, a different derivation, a disjoint file namespace. It is a mode
	// rather than an additional pass because a seed materializes ONE schema and
	// the two families need different ones.
	Nested bool
}