plan

type AuthDecision struct {
	ClusterID      string           `json:"cluster_id"`
	SourceAuths    []string         `json:"source_auths_detected"`
	TargetMappings []AuthMappingRow `json:"target_mappings,omitempty"`
	// OverrideRejected is true when the (cluster-scoped or global)
	// `target_auth_method` override was set to a value outside the
	// recognised enum — the row's `effective_target` reflects the per-
	// source default. The renderer surfaces an inline marker in §4 so
	// a reader scanning the table sees why this cluster's target
	// differs from peers without scrolling to the Actions Needed
	// section to read the typo OQ.
	OverrideRejected bool `json:"override_rejected,omitempty"`
	// RejectedOverrideValue is the customer-supplied invalid value;
	// surfaced in the renderer footnote so the reader recognises the
	// typo at a glance.
	RejectedOverrideValue string `json:"rejected_override_value,omitempty"`
}

type AuthMapping struct {
	Target            string `yaml:"target"`
	GatewayCompatible bool   `yaml:"gateway_compatible"`
	TransparentSwap   bool   `yaml:"transparent_swap"`
	Note              string `yaml:"note"`
	Source            string `yaml:"source"`
	LastVerified      string `yaml:"last_verified"`
}

type AuthMappingRow struct {
	SourceAuth        string `json:"source_auth"`
	EffectiveTarget   string `json:"effective_target"`
	GatewayCompatible bool   `json:"gateway_compatible"`
	TransparentSwap   bool   `json:"transparent_swap"`
	Note              string `json:"note,omitempty"`
	// Source + LastVerified carry per-row provenance from the
	// auth_mapping table in plan-config.yaml — surfaced in the
	// rendered Plan as a footnote so the reviewer can audit where the
	// recommendation comes from.
	Source       string `json:"source,omitempty"`
	LastVerified string `json:"last_verified,omitempty"`
}

type ClusterCutoverOverride struct {
	ClusterID             string            `json:"cluster_id"`
	Style                 CutoverStyle      `json:"style"`
	SubPattern            CutoverSubPattern `json:"sub_pattern,omitempty"`
	GatewayMediated       GatewayMediated   `json:"gateway_mediated"`
	OverrideRejected      bool              `json:"override_rejected,omitempty"`
	RejectedOverrideValue string            `json:"rejected_override_value,omitempty"`
}

type ClusterLinking struct {
	SourceMinKafkaVersion string `yaml:"source_min_kafka_version"`
	ExpressTierSupported  string `yaml:"express_tier_supported"`
	Source                string `yaml:"source"`
}

type ClusterPlanInputs struct {
	SLATarget                            *string  `yaml:"sla_target,omitempty"                                 json:"sla_target,omitempty"`
	HeadroomFraction                     *float64 `yaml:"headroom_fraction,omitempty"                          json:"headroom_fraction,omitempty"`
	SpikyWorkloadRatio                   *float64 `yaml:"spiky_workload_ratio,omitempty"                       json:"spiky_workload_ratio,omitempty"`
	EnforceSchemasAtTheBroker            *bool    `yaml:"enforce_schemas_at_the_broker,omitempty"              json:"enforce_schemas_at_the_broker,omitempty"`
	RequiresHighThroughputRESTProduceAPI *bool    `yaml:"requires_high_throughput_rest_produce_api,omitempty"  json:"requires_high_throughput_rest_produce_api,omitempty"`
	Requires9995SLAWithinSingleZone      *bool    `yaml:"requires_99_95_sla_within_a_single_zone,omitempty"    json:"requires_99_95_sla_within_a_single_zone,omitempty"`
	TargetCloud                          *string  `yaml:"target_cloud,omitempty"                               json:"target_cloud,omitempty"`
	ExistingVPCConnectivity              *string  `yaml:"existing_vpc_connectivity,omitempty"                  json:"existing_vpc_connectivity,omitempty"`
	CCEgressRequired                     *bool    `yaml:"cc_egress_required,omitempty"                         json:"cc_egress_required,omitempty"`
	ProjectedPNIGatewayCount             *int     `yaml:"projected_pni_gateway_count,omitempty"                json:"projected_pni_gateway_count,omitempty"`
	// TargetAuthMethod is the per-cluster override for the target
	// auth verdict. Same enum as the global field.
	TargetAuthMethod *string `yaml:"target_auth_method,omitempty" json:"target_auth_method,omitempty"`
	// DowntimeTolerance is the per-cluster override for the cutover
	// style. Same enum as the global field. Use when heterogeneous
	// fleets need different cutover styles per cluster — e.g. a
	// latency-sensitive service on Blue/Green while batch jobs run
	// Stop-Restart-Repeat. Without this, the customer would have to
	// slice the state file and run kcp once per cluster subset.
	DowntimeTolerance *string `yaml:"downtime_tolerance,omitempty" json:"downtime_tolerance,omitempty"`
	// SubPattern is the per-cluster override; only meaningful when the
	// resolved style is Stop-Restart-Repeat. Mirrors the global field.
	SubPattern *string `yaml:"sub_pattern,omitempty" json:"sub_pattern,omitempty"`
}

type ClusterSizing struct {
	ClusterID string `json:"cluster_id"`
	// SizedInMBps / SizedOutMBps hold the throughput at the configured
	// `sizing_percentile` (default p95; alternates p99, max). Read
	// `plan.inputs.sizing_percentile` to see which percentile was used.
	SizedInMBps        float64 `json:"sized_in_mbps"`
	SizedOutMBps       float64 `json:"sized_out_mbps"`
	PeakInMBps         float64 `json:"peak_in_mbps"`
	PeakOutMBps        float64 `json:"peak_out_mbps"`
	UserPartitions     int     `json:"user_partitions"`
	InternalPartitions int     `json:"internal_partitions"`
	IngressRatio       float64 `json:"ingress_ratio"`
	EgressRatio        float64 `json:"egress_ratio"`
	PartitionRatio     float64 `json:"partition_ratio"`
	MaxRatio           float64 `json:"max_ratio"`
	// MaxRatioDriver names which of the three dimensions produced MaxRatio:
	// "ingress", "egress", or "partitions". Tracked at compute time so the
	// renderer never has to do a float-equality comparison to recover it.
	MaxRatioDriver      string          `json:"max_ratio_driver,omitempty"`
	SizedECKU           int             `json:"sized_ecku"`
	SLAFloorECKU        int             `json:"sla_floor_ecku"`
	FinalECKU           int             `json:"final_ecku"`
	PeakBurstInRatio    float64         `json:"peak_burst_in_ratio"`
	PeakBurstOutRatio   float64         `json:"peak_burst_out_ratio"`
	PeakBurstECKU       int             `json:"peak_burst_ecku"`
	PeakBurstPctOfPLCap float64         `json:"peak_burst_pct_of_pl_cap"`
	SpikyIngress        bool            `json:"spiky_ingress"`
	SpikyEgress         bool            `json:"spiky_egress"`
	Citations           []FieldCitation `json:"citations"`

	// Degraded is true when throughput metrics were missing from the state
	// file. Numbers fall back to the SLA floor and the renderer surfaces
	// the gap rather than silently asserting a sized eCKU.
	Degraded       bool   `json:"degraded,omitempty"`
	DegradedReason string `json:"degraded_reason,omitempty"`

	// InputsMissing names load-bearing scan signals that weren't
	// available when sizing was computed (e.g. `"topics"`, `"acls"`,
	// `"brokers"`). The verdict from downstream decisions may still be
	// solid if driven by customer-declared flags; the renderer reads
	// this list to mark sizing as provisional rather than blanket-
	// deferring the cluster.
	InputsMissing []string `json:"inputs_missing,omitempty"`
}

type ClusterType string

type ClusterTypeDecision struct {
	ClusterID string             `json:"cluster_id"`
	Verdict   ClusterType        `json:"verdict"`
	Triggers  []HardLimitTrigger `json:"triggers,omitempty"`
	// Topology is populated for Dedicated verdicts (MZ default; SZ when the
	// 99.95% single-zone SLA rule fires). Empty for Enterprise.
	Topology Topology `json:"topology,omitempty"`
	// FinalCKU mirrors the sizing's FinalECKU under the Dedicated unit
	// (Confluent Kafka Unit). Set only when Verdict == Dedicated.
	FinalCKU *int `json:"final_cku,omitempty"`
	// InputsMissing names load-bearing scan / plan-input signals that
	// weren't available when this decision was computed (e.g. `"topics"`,
	// `"acls"`). **Observational only** — set post-hoc in
	// `PlanService.Build` after `DecideClusterType` has already run; the
	// Verdict itself was computed against whatever inputs WERE present.
	// Markdown reads this to flag the sizing column as provisional;
	// JSON consumers can branch on the list.
	InputsMissing []string `json:"inputs_missing,omitempty"`
	// EvaluatedRules is the full audit trail for the hard-limit catalog
	// against this cluster — every rule's outcome (fired / not_fired /
	// skipped) with evidence. Read-only audit shape; the renderer
	// surfaces it as a collapsed appendix.
	EvaluatedRules []RuleEvaluation `json:"evaluated_rules,omitempty"`
}

type CostReconciliationCfg struct {
	UsageFamilies []string `yaml:"usage_families"`
}

type CostReconciliationSection struct {
	Candidates []HiddenClusterCandidate `json:"candidates"`
}

type CutoverDecision struct {
	Style                CutoverStyle         `json:"style"`
	SubPattern           CutoverSubPattern    `json:"sub_pattern,omitempty"` // only when Style == StopRestartRepeat
	GatewayMediated      GatewayMediated      `json:"gateway_mediated"`
	RecommendationStatus RecommendationStatus `json:"recommendation_status"`
	// AlternativesShown lists the styles the renderer explains for
	// trust but doesn't recommend — gives the reader the full pattern
	// set without forcing a deeper decision tree.
	AlternativesShown []CutoverStyle `json:"alternatives_shown_for_trust,omitempty"`
	Prereqs           []Prereq       `json:"prereqs,omitempty"`
}

type CutoverStyle string

type CutoverSubPattern string

type EffortSignal struct {
	ID    string `json:"id"`
	Label string `json:"label"`
	// Count is the integer signal value. `nil` means the signal is
	// structurally unobservable (the upstream scan didn't run);
	// `0` means the scan ran and returned zero hits.
	Count *int   `json:"count"`
	Note  string `json:"note,omitempty"`
}

type EffortSignalsSection struct {
	Signals []EffortSignal `json:"signals"`
}

type EnterpriseCaps struct {
	PerECKUIngressMBps   int    `yaml:"per_eCKU_ingress_mbps"`
	PerECKUEgressMBps    int    `yaml:"per_eCKU_egress_mbps"`
	PerECKUPartitionRate int    `yaml:"per_eCKU_partition_rate"`
	PrivateLinkMaxECKU   int    `yaml:"privatelink_max_eCKU"`
	PNIMaxECKU           int    `yaml:"pni_max_eCKU"`
	ACLCountCap          int    `yaml:"acl_count_cap"`
	Source               string `yaml:"source"`
}

type FieldCitation struct {
	Path  string `json:"path"`
	Value any    `json:"value"`
}

type GatewayMediated string

type HardLimitTrigger struct {
	RowID       string `json:"row_id"`
	Description string `json:"description"`
	Evidence    string `json:"evidence"`
	// CustomerDeclared marks rules whose only signal is a customer-set
	// `plan-inputs.yaml` flag. Renderer surfaces a cost callout on these
	// so a wrong `true` doesn't quietly flip the verdict from Enterprise
	// to Dedicated (Dedicated has a higher monthly cost).
	CustomerDeclared bool `json:"customer_declared,omitempty"`
}

type HiddenClusterCandidate struct {
	Region         string  `json:"region"`
	InstanceType   string  `json:"instance_type"`
	TotalSpend     float64 `json:"total_spend"`
	MonthsObserved int     `json:"months_observed,omitempty"`
	DaysObserved   int     `json:"days_observed,omitempty"`
}

type Networking string

type NetworkingDecision struct {
	ClusterID       string     `json:"cluster_id"`
	Verdict         Networking `json:"verdict"`
	PeakBurstECKU   int        `json:"peak_burst_ecku"`
	PercentageOfCap float64    `json:"percentage_of_cap"`
	Reason          string     `json:"reason"`
	// InputsMissing — see ClusterTypeDecision.InputsMissing. Populated
	// in lockstep so JSON consumers see the same gating signal on both
	// decisions for an affected cluster. **JSON-consumer-only**: the
	// markdown renderer reads the sister field on `ClusterTypeDecision`
	// (and the same list on `ClusterSizing`) — this copy is here so
	// downstream JSON branching doesn't need a cross-reference lookup.
	InputsMissing []string `json:"inputs_missing,omitempty"`
}

type OpenQuestion struct {
	ID         string `json:"id"`
	ClusterID  string `json:"cluster_id,omitempty"`
	Title      string `json:"title"`
	Body       string `json:"body"`
	HowToClose string `json:"how_to_close"`
}

type Plan struct {
	Header              PlanHeader            `json:"header"`
	Inputs              PlanInputsResolved    `json:"inputs"`
	SourceEnvironment   SourceEnvironment     `json:"source_environment"`
	Sizing              []ClusterSizing       `json:"sizing"`
	ClusterTypeDecision []ClusterTypeDecision `json:"cluster_type_decision"`
	NetworkingDecision  []NetworkingDecision  `json:"networking_decision"`
	// Cutover is the fleet-wide cutover decision — the default style
	// applied to every cluster that doesn't carry a per-cluster
	// override in CutoverOverrides. Nil when no clusters were found in
	// the state file.
	Cutover *CutoverDecision `json:"cutover,omitempty"`
	// CutoverOverrides carries clusters whose resolved
	// `downtime_tolerance` (or `sub_pattern`) differs from the fleet
	// — only the clusters that diverge appear here, so an
	// all-homogeneous fleet keeps this slice empty. Heterogeneous
	// fleets previously had to slice the state file and run kcp once
	// per subset; per-cluster overrides remove that workaround.
	CutoverOverrides []ClusterCutoverOverride `json:"cutover_overrides,omitempty"`
	// Auth is per-cluster — source auth methods differ across MSK clusters
	// in the same fleet, so each gets its own source→target mapping.
	Auth []AuthDecision `json:"auth,omitempty"`
	// Schema is fleet-wide (the schema registry is one shared system,
	// not per-cluster). Nil when the section is omitted — currently the
	// `schemaless` path (`sr_detected == none` AND
	// `schema_strategy == no_schemas`).
	Schema *SchemaDecision `json:"schema,omitempty"`
	// RedFlags surfaces the boolean trigger rows over the Plan + state
	// file. Triggered rows are items to discuss with the SE; each row
	// carries its own evidence (field path + value) so the discussion
	// is grounded in the scan, not on inference.
	RedFlags *RedFlagsSection `json:"red_flags,omitempty"`
	// EffortSignals is the list of quantitative signals the customer's
	// PM consumes to scope migration effort. Counts only, no
	// day-estimate.
	EffortSignals *EffortSignalsSection `json:"effort_signals,omitempty"`
	// TieredStorage is a per-cluster section describing the
	// three-dimension trade-off (mechanism / duration / cost direction)
	// for clusters with MSK tiered storage enabled. Nil when no source
	// cluster has TIERED storage.
	TieredStorage *TieredStorageSection `json:"tiered_storage,omitempty"`
	// CostReconciliation lists MSK clusters that show up in the AWS
	// cost report but were NOT discovered by `kcp discover`. Sorted by
	// TotalSpend desc. Nil when cost data is empty or the diff is
	// clean.
	CostReconciliation *CostReconciliationSection `json:"cost_reconciliation,omitempty"`
	SizingAppendix     []SizingMathDetail         `json:"sizing_appendix"`
	OpenQuestions      []OpenQuestion             `json:"open_questions,omitempty"`
}

type PlanConfig struct {
	SchemaVersion            int    `yaml:"schema_version"`
	LastVerified             string `yaml:"last_verified"`
	KCPVersionAtVerification string `yaml:"kcp_version_at_verification"`

	EnterpriseCaps     EnterpriseCaps         `yaml:"enterprise_caps"`
	ClusterLinking     ClusterLinking         `yaml:"cluster_linking"`
	SchemaLinking      SchemaLinking          `yaml:"schema_linking"`
	PlanInputDefaults  PlanInputDefaults      `yaml:"plan_input_defaults"`
	AuthMapping        map[string]AuthMapping `yaml:"auth_mapping"`
	Thresholds         Thresholds             `yaml:"thresholds"`
	CostReconciliation CostReconciliationCfg  `yaml:"cost_reconciliation"`
}

type PlanHeader struct {
	Source        string    `json:"source"`
	StateFilePath string    `json:"state_file_path"`
	KCPVersion    string    `json:"kcp_version"`
	GeneratedAt   time.Time `json:"generated_at"`
	// StateGeneratedAt is the timestamp the source state file was
	// produced (state.Timestamp). Surfaced in the rendered Plan so a
	// reviewer can see how fresh the underlying scan is — important
	// for negative-evidence claims like "0 ACLs" in Appendix A2.
	StateGeneratedAt time.Time `json:"state_generated_at,omitempty"`

	// PlanSchemaVersion identifies the JSON shape of the Plan. Stable
	// at "1" now that the full deterministic decision set ships
	// (sizing / cluster type / networking / cutover / auth / schema /
	// red flags / effort signals / tiered storage / cost
	// reconciliation). Additive top-level keys at this version are
	// allowed; renames or removals require a version bump.
	PlanSchemaVersion string `json:"plan_schema_version"`
}

type PlanInputDefaults struct {
	SizingPercentile   string         `yaml:"sizing_percentile"`
	HeadroomFraction   float64        `yaml:"headroom_fraction"`
	SpikyWorkloadRatio float64        `yaml:"spiky_workload_ratio"`
	SLAFloorECKU       map[string]int `yaml:"sla_floor_eCKU"`

	// Customer-declared hard requirements (all default false).
	EnforceSchemasAtTheBroker            bool `yaml:"enforce_schemas_at_the_broker"`
	RequiresHighThroughputRESTProduceAPI bool `yaml:"requires_high_throughput_rest_produce_api"`
	Requires9995SLAWithinSingleZone      bool `yaml:"requires_99_95_sla_within_a_single_zone"`

	// Target cloud + existing VPC connectivity (Dedicated-path networking).
	TargetCloud             string `yaml:"target_cloud"`
	ExistingVPCConnectivity string `yaml:"existing_vpc_connectivity"`

	// Networking triggers (PNI→PrivateLink) — see PlanInputsResolved.
	CCEgressRequired         bool `yaml:"cc_egress_required"`
	ProjectedPNIGatewayCount int  `yaml:"projected_pni_gateway_count"`

	// Cutover defaults.
	DowntimeTolerance            string `yaml:"downtime_tolerance"`
	SubPattern                   string `yaml:"sub_pattern"`
	PreferGateway                bool   `yaml:"prefer_gateway"`
	ConfluentForKubernetesStatus string `yaml:"confluent_for_kubernetes_status"`
	CCGatewayLicenseStatus       string `yaml:"cc_gateway_license_status"`
	IAMPreMigrationStatus        string `yaml:"iam_pre_migration_status"`

	// Auth defaults.
	TargetAuthMethod string `yaml:"target_auth_method"`

	// Schema-migration defaults. Defaults below resolve to
	// `unknown` so first-run plans always ask the customer to declare
	// strategy + reachability + CP version/edition rather than silently
	// picking a path.
	SchemaStrategy       string `yaml:"schema_strategy"`
	ConfluentSRCPVersion string `yaml:"confluent_sr_cp_version,omitempty"`
	ConfluentSRCPEdition string `yaml:"confluent_sr_cp_edition,omitempty"`
}

type PlanInputs struct {
	// Sizing overrides (defaults live in plan-config.yaml).
	SLATarget          *string  `yaml:"sla_target,omitempty"          json:"sla_target,omitempty"`
	SizingPercentile   *string  `yaml:"sizing_percentile,omitempty"   json:"sizing_percentile,omitempty"`
	HeadroomFraction   *float64 `yaml:"headroom_fraction,omitempty"   json:"headroom_fraction,omitempty"`
	SpikyWorkloadRatio *float64 `yaml:"spiky_workload_ratio,omitempty" json:"spiky_workload_ratio,omitempty"`

	// Customer-declared hard requirements that force Dedicated.
	// Default `false`; only the customer (or an SE on their behalf) sets these.
	EnforceSchemasAtTheBroker            *bool `yaml:"enforce_schemas_at_the_broker,omitempty"            json:"enforce_schemas_at_the_broker,omitempty"`
	RequiresHighThroughputRESTProduceAPI *bool `yaml:"requires_high_throughput_rest_produce_api,omitempty" json:"requires_high_throughput_rest_produce_api,omitempty"`
	Requires9995SLAWithinSingleZone      *bool `yaml:"requires_99_95_sla_within_a_single_zone,omitempty"  json:"requires_99_95_sla_within_a_single_zone,omitempty"`

	// When source auth includes mTLS AND target_cloud is not `aws`,
	// Dedicated is required because only Dedicated supports mTLS on
	// Azure / GCP. MSK is AWS-only so this defaults to `aws`.
	TargetCloud *string `yaml:"target_cloud,omitempty" json:"target_cloud,omitempty"`

	// Existing VPC connectivity to MSK. When set to `transit_gateway`
	// or `vpc_peering` and the cluster is Dedicated, the same pattern
	// is recommended for Confluent Cloud. `privatelink_or_pni` (default)
	// keeps the AWS-to-AWS Enterprise default (PNI) unless one of the
	// PrivateLink triggers fires (see CCEgressRequired,
	// ProjectedPNIGatewayCount, non-AWS target_cloud).
	ExistingVPCConnectivity *string `yaml:"existing_vpc_connectivity,omitempty" json:"existing_vpc_connectivity,omitempty"`

	// CCEgressRequired = "Do CC-side workloads need to push traffic
	// back into your customer VPC?" PNI does not natively support
	// egress from CC into customer infrastructure; when true the
	// networking default flips from PNI to PrivateLink.
	CCEgressRequired *bool `yaml:"cc_egress_required,omitempty" json:"cc_egress_required,omitempty"`

	// ProjectedPNIGatewayCount — projected PNI gateway count for the
	// deployment. When ≥ 2, the recommendation flips from PNI to
	// PrivateLink. Default 1 (single gateway).
	ProjectedPNIGatewayCount *int `yaml:"projected_pni_gateway_count,omitempty" json:"projected_pni_gateway_count,omitempty"`

	// DowntimeTolerance maps 1:1 to a cutover style. Enum values:
	//   zero                          → Blue/Green
	//   seconds_per_service           → Stop-Restart-Repeat (gateway REQUIRED)
	//   minutes_per_service           → Stop-Restart-Repeat (gateway optional)
	//   scheduled_window_sequential   → Stop-Wait-Restart
	//   scheduled_window_all_at_once  → Restart-All-At-Once
	//   let_confluent_choose          → Stop-Restart-Repeat (Confluent default)
	DowntimeTolerance *string `yaml:"downtime_tolerance,omitempty" json:"downtime_tolerance,omitempty"`

	// SubPattern is only consulted when the resolved style is
	// Stop-Restart-Repeat. Values: `app-by-app` (default) | `topic-by-topic`.
	SubPattern *string `yaml:"sub_pattern,omitempty" json:"sub_pattern,omitempty"`

	// PreferGateway lets the customer opt out of the gateway-mediated
	// recommendation even when they're eligible. Default true mirrors
	// Confluent's canonical recommendation; set false for plain Cluster
	// Linking.
	PreferGateway *bool `yaml:"prefer_gateway,omitempty" json:"prefer_gateway,omitempty"`

	// Gateway prereq statuses. Each is one of `not_started` |
	// `in_progress` | `complete`. Eligibility for the canonical
	// recommendation requires all three to be at `in_progress` or
	// `complete` (with the IAM prereq only relevant when IAM is
	// detected on any source cluster).
	ConfluentForKubernetesStatus *string `yaml:"confluent_for_kubernetes_status,omitempty" json:"confluent_for_kubernetes_status,omitempty"`
	CCGatewayLicenseStatus       *string `yaml:"cc_gateway_license_status,omitempty"       json:"cc_gateway_license_status,omitempty"`
	IAMPreMigrationStatus        *string `yaml:"iam_pre_migration_status,omitempty"        json:"iam_pre_migration_status,omitempty"`

	// TargetAuthMethod overrides the default target auth (looked up
	// per source auth in `auth_mapping`). Enum:
	// `confluent_cloud_api_keys` (default) | `mtls` | `oauth`.
	// Per-cluster override available via `clusters[name].target_auth_method`.
	TargetAuthMethod *string `yaml:"target_auth_method,omitempty" json:"target_auth_method,omitempty"`

	// SchemaStrategy declares the customer's intent for schemas. Enum:
	//   unknown                          → emit OQ (default; first-run safety)
	//   no_schemas                       → schemaless path (omit §Schema)
	//   adopt_schemas_during_migration   → start with no source SR, adopt CC SR
	//   migrate_existing_schema_registry → run the SR-detected path
	SchemaStrategy *string `yaml:"schema_strategy,omitempty" json:"schema_strategy,omitempty"`

	// SourceSROutboundReachableToCC is the customer's network-reachability
	// declaration: can the source Confluent SR reach the CC SR endpoint
	// outbound? Schema Linking's Schema Exporter is one-directional from
	// source SR → CC SR, so without this the gateway-eligible verdict
	// can't hold. Default nil = unknown.
	SourceSROutboundReachableToCC *bool `yaml:"source_sr_outbound_reachable_to_cc,omitempty" json:"source_sr_outbound_reachable_to_cc,omitempty"`

	// ConfluentSRCPVersion is the customer-declared Confluent Platform
	// version of the source Schema Registry. Schema Linking requires
	// CP 7.0 or later. Default nil = unknown — the scanner does not
	// populate this today, so the customer declares it via plan-inputs.
	// Accepted shape: "7.5.1" / "7.0" / "6.2" — string compare against
	// the configured floor.
	ConfluentSRCPVersion *string `yaml:"confluent_sr_cp_version,omitempty" json:"confluent_sr_cp_version,omitempty"`

	// ConfluentSRCPEdition is the customer-declared Confluent Platform
	// edition. Schema Linking requires `enterprise` (CP 7.0 Community
	// does not include it). Enum: `enterprise` | `community`.
	ConfluentSRCPEdition *string `yaml:"confluent_sr_cp_edition,omitempty" json:"confluent_sr_cp_edition,omitempty"`

	// ExactlyOnceTransactionsInUse declares whether the source has
	// EOS / Kafka transactions enabled. There is no detectable state
	// signal for this; customer-only. Default nil = unknown — the
	// Red Flag row surfaces as "not scanned" rather than firing false.
	ExactlyOnceTransactionsInUse *bool `yaml:"exactly_once_transactions_in_use,omitempty" json:"exactly_once_transactions_in_use,omitempty"`

	// KafkaStreamsInUse declares whether Kafka Streams apps consume
	// from the source. The Red Flag detector also runs a
	// topic-pattern scan (`-changelog` / `-repartition`); this flag
	// lets the customer affirm even when topic patterns miss.
	KafkaStreamsInUse *bool `yaml:"kafka_streams_in_use,omitempty" json:"kafka_streams_in_use,omitempty"`

	// ConsumerHistoryRequirement declares whether downstream consumers
	// actually need to replay historical (tiered) data. Enum:
	//   required (default)  → backfill is required; weigh the 3
	//                         dimensions (mechanism / duration / cost)
	//   not_required        → real-time-only consumers; defer to the
	//                         account team for the cascade of
	//                         per-topic + consumer-offset decisions
	//   unknown             → customer hasn't decided yet
	ConsumerHistoryRequirement *string `yaml:"consumer_history_requirement,omitempty" json:"consumer_history_requirement,omitempty"`

	// HistoricalDataStrategy is the customer's preferred path when
	// tiered-storage backfill IS required. Enum:
	//   keep_msk_running_until_data_expires
	//   bulk_load_historical_via_external_tool
	//   defer_to_account_team   (default for the not_required cascade)
	HistoricalDataStrategy *string `yaml:"historical_data_strategy,omitempty" json:"historical_data_strategy,omitempty"`

	// Clusters — per-cluster overrides keyed by source cluster name.
	// Heterogeneous fleets (mixed-SLA, mixed-tier) need finer-grained
	// inputs than the global flags above; without this, flipping a
	// single global flag like `requires_99_95_sla_within_a_single_zone:
	// true` would force Dedicated SZ on every cluster including
	// idle / Zookeeper / Serverless ones. Resolution: per-cluster
	// override wins; fall back to global default. Only the subset of
	// fields that makes sense per-cluster lives here.
	Clusters map[string]ClusterPlanInputs `yaml:"clusters,omitempty" json:"clusters,omitempty"`
}

type PlanInputsResolved struct {
	// Raw preserves the original customer-supplied `PlanInputs`. **Note:**
	// the flat fields below carry the *global* resolved view; per-cluster
	// overrides (`Raw.Clusters[<name>]`) are layered on top per cluster
	// inside `PlanService.Build` via `ResolvePlanInputsForCluster` — they
	// are NOT applied to the values stored here. JSON consumers wanting
	// the per-cluster view should re-run the resolver against `Raw`.
	Raw *PlanInputs `json:"raw,omitempty"`

	SLATarget          string  `json:"sla_target"`
	SizingPercentile   string  `json:"sizing_percentile"`
	HeadroomFraction   float64 `json:"headroom_fraction"`
	SpikyWorkloadRatio float64 `json:"spiky_workload_ratio"`

	// Customer-declared hard requirements. Booleans (not *bool) — defaults
	// resolve to false, which is the safe verdict (no escalation to Dedicated).
	EnforceSchemasAtTheBroker            bool `json:"enforce_schemas_at_the_broker"`
	RequiresHighThroughputRESTProduceAPI bool `json:"requires_high_throughput_rest_produce_api"`
	Requires9995SLAWithinSingleZone      bool `json:"requires_99_95_sla_within_a_single_zone"`

	// Target cloud + existing VPC connectivity (Dedicated-path networking).
	TargetCloud             string `json:"target_cloud"`
	ExistingVPCConnectivity string `json:"existing_vpc_connectivity"`

	// Networking triggers that flip the AWS-Enterprise default from PNI
	// to PrivateLink. CCEgressRequired and ProjectedPNIGatewayCount are
	// workload properties, not state-derived.
	CCEgressRequired         bool `json:"cc_egress_required"`
	ProjectedPNIGatewayCount int  `json:"projected_pni_gateway_count"`

	// Cutover — `downtime_tolerance` drives the style; the others
	// govern gateway eligibility + opt-out.
	DowntimeTolerance            string `json:"downtime_tolerance"`
	SubPattern                   string `json:"sub_pattern"`
	PreferGateway                bool   `json:"prefer_gateway"`
	ConfluentForKubernetesStatus string `json:"confluent_for_kubernetes_status"`
	CCGatewayLicenseStatus       string `json:"cc_gateway_license_status"`
	IAMPreMigrationStatus        string `json:"iam_pre_migration_status"`

	// Auth — target verdict; cluster-level override flows through
	// `applyClusterOverride` per the heterogeneous-fleet rule.
	TargetAuthMethod string `json:"target_auth_method"`

	// Schema migration. Strings/bools resolved from the customer
	// input with `unknown` / nil-tri-state semantics: SchemaStrategy
	// defaults to `unknown` so first-run plans don't fire spurious
	// schemaless verdicts. The CP version + edition + outbound
	// reachability stay nil-tri-state because "false" and "unknown"
	// produce different OQs.
	SchemaStrategy                string `json:"schema_strategy"`
	SourceSROutboundReachableToCC *bool  `json:"source_sr_outbound_reachable_to_cc,omitempty"`
	ConfluentSRCPVersion          string `json:"confluent_sr_cp_version,omitempty"`
	ConfluentSRCPEdition          string `json:"confluent_sr_cp_edition,omitempty"`

	// Red Flags customer flags — nil tri-state.
	ExactlyOnceTransactionsInUse *bool `json:"exactly_once_transactions_in_use,omitempty"`
	KafkaStreamsInUse            *bool `json:"kafka_streams_in_use,omitempty"`

	// Tiered Storage knobs. Strings normalized to lowercase tokens by
	// the resolver. `ConsumerHistoryRequirement` empty means "not
	// declared" and is defaulted to `required` by the detector (so the
	// section surfaces the trade-off rather than the unknown-OQ
	// branch). `HistoricalDataStrategy` empty is "not declared" and
	// stays empty unless `ConsumerHistoryRequirement == not_required`,
	// in which case it cascades to `defer_to_account_team`.
	ConsumerHistoryRequirement string `json:"consumer_history_requirement,omitempty"`
	HistoricalDataStrategy     string `json:"historical_data_strategy,omitempty"`
}

type PlanService struct {
	// contains filtered or unexported fields
}

type Prereq struct {
	Description string       `json:"description"`
	Status      PrereqStatus `json:"status"`
}

type PrereqStatus string

type RecommendationStatus string

type RedFlag struct {
	ID     string        `json:"id"`
	Title  string        `json:"title"`
	Status RedFlagStatus `json:"status"`
	// Evidence is the human-readable prose surfaced in the rendered
	// Plan. Keep it under control of the row's evaluator so a reader
	// can tell at a glance WHY the row fired.
	Evidence string `json:"evidence,omitempty"`
	// EvidenceFields carries the structured signals the evaluator
	// computed: scalar counts, cluster lists, version strings, etc.
	// Downstream JSON consumers branch on these instead of parsing
	// `Evidence`. Stable shape (additive only) at
	// `plan_schema_version: "1"`.
	EvidenceFields map[string]any `json:"evidence_fields,omitempty"`
	ClusterID      string         `json:"cluster_id,omitempty"`
}

type RedFlagStatus string

type RedFlagsSection struct {
	Rows []RedFlag `json:"rows"`
}

type RuleEvaluation struct {
	RowID       string      `json:"row_id"`
	Description string      `json:"description"`
	Outcome     RuleOutcome `json:"outcome"`
	Evidence    string      `json:"evidence,omitempty"`
	SkipReason  string      `json:"skip_reason,omitempty"`
}

type RuleOutcome string

type SchemaDecision struct {
	Source SchemaSource `json:"source"`
	// Paths lists every recommended verdict that applies, in
	// rendering order. Single-source cases have len(Paths)==1; the
	// dual-source `confluent_and_glue` case has 2 entries (Glue
	// first — it's the automatable path; Confluent path second).
	//
	// **JSON-consumer note for dual-source.** When Source is
	// `confluent_and_glue` and len(Paths)==1 (only the Glue arm
	// landed), the Confluent arm is in one of two states:
	//   (a) eligibility flags undeclared — pending. Disambiguate by
	//       reading the OpenQuestions for `schema_linking_eligibility_unknown`.
	//   (b) all three eligibility flags resolved AND at least one is
	//       false — verified ineligible. The OQ
	//       `schema_linking_ineligible` will be present.
	// Reading `MeetsCPVersionFloor` / `MeetsCPEditionRequirement` /
	// `SourceSROutboundReachable` tri-states gives the same signal.
	Paths []SchemaPath `json:"paths"`
	// Schema-Linking eligibility constraints — all three must hold for
	// SchemaPathSchemaLinking. Populated only when Source includes
	// `confluent`; the renderer prints a 3-row eligibility table from
	// these flags. *KnownAsTrue distinguishes "verified true" from
	// "verified false" vs "unknown" — when any one is unknown the
	// resulting Paths include `unknown` and the OQ asks the customer
	// to confirm rather than guessing.
	MeetsCPVersionFloor       *bool `json:"meets_cp_version_floor,omitempty"`
	MeetsCPEditionRequirement *bool `json:"meets_cp_edition_requirement,omitempty"`
	SourceSROutboundReachable *bool `json:"source_sr_outbound_reachable,omitempty"`
	// GlueRegistries lists the Glue registry names detected on the
	// source side — surfaced in the Terraform command the renderer
	// emits for SchemaPathMigrateGlue (one apply per registry).
	GlueRegistries []string `json:"glue_registries,omitempty"`
	// ConfluentSRURLs lists the Confluent SR URLs detected. Surfaced
	// in the eligibility table header so a reader knows which SR the
	// verdict applies to.
	ConfluentSRURLs []string `json:"confluent_sr_urls,omitempty"`
}

type SchemaLinking struct {
	MinCPVersion      string `yaml:"min_cp_version"`
	RequiresCPEdition string `yaml:"requires_cp_edition"`
	Source            string `yaml:"source"`
	LastVerified      string `yaml:"last_verified"`
}

type SchemaPath string

type SchemaSource string

type SizingMathDetail struct {
	ClusterID         string          `json:"cluster_id"`
	Formula           string          `json:"formula"`
	IntermediateSteps []string        `json:"intermediate_steps"`
	Citations         []FieldCitation `json:"citations,omitempty"`
}

type SourceClusterSummary struct {
	ClusterID    string `json:"cluster_id"`
	Region       string `json:"region"`
	BrokerCount  int    `json:"broker_count"`
	TopicCount   int    `json:"topic_count"`
	KafkaVersion string `json:"kafka_version,omitempty"`
	// IsServerless flags MSK Serverless source clusters. Set to true
	// when MskClusterConfig.ClusterType == "SERVERLESS"; the renderer
	// uses it to suppress Provisioned-only framing (broker counts,
	// "incomplete scan" guidance) that doesn't apply to Serverless.
	IsServerless bool `json:"is_serverless,omitempty"`
	// SourceAuths lists the auth methods enabled on the source cluster
	// (stable enum tokens: scram, iam, mtls, unauth). Drawn from the
	// same MSK ClientAuthentication signals AuthDecision reads — surfaced here in
	// §1 so a reader scanning the Source Environment table sees the
	// auth posture alongside brokers / topics before the §4 mapping.
	SourceAuths []string `json:"source_auths,omitempty"`
}

type SourceEnvironment struct {
	Clusters     []SourceClusterSummary `json:"clusters"`
	TotalRegions int                    `json:"total_regions"`
}

type Thresholds struct {
	// StaleStateDays — emit the state-file-stale OQ when the state
	// snapshot is older than this many days.
	StaleStateDays int `yaml:"stale_state_days"`
	// PNIGatewayBreakeven — projected PNI gateway count at or above
	// which the recommendation flips from PNI to PrivateLink.
	PNIGatewayBreakeven int `yaml:"pni_gateway_breakeven"`
	// PartitionApproachingFraction — Red Flag row 5 fires when
	// user-topic partitions exceed this fraction of the cluster's
	// sized eCKU capacity (per_eCKU_partition_rate * FinalECKU).
	// 0.30 means "fire at 30% of sized capacity"; pre-fix this was
	// hardcoded in red_flags.go.
	PartitionApproachingFraction float64 `yaml:"partition_approaching_fraction"`
}

type TieredStorageCluster struct {
	ClusterID   string `json:"cluster_id"`
	StorageMode string `json:"storage_mode"`
	// RemoteLogSizeBytes is the peak observed footprint (CloudWatch
	// Maximum aggregate) — appropriate for a monotonically-
	// accumulating gauge. Falls back to Average when Max isn't
	// populated. Zero when the metric wasn't collected or the
	// cluster doesn't have tiered data yet.
	RemoteLogSizeBytes float64 `json:"remote_log_size_bytes,omitempty"`
}

type TieredStorageSection struct {
	Clusters                   []TieredStorageCluster `json:"clusters"`
	ConsumerHistoryRequirement string                 `json:"consumer_history_requirement"`
	HistoricalDataStrategy     string                 `json:"historical_data_strategy"`
}

type Topology string