risk

type AlertCandidate struct {
	EpisodeKey          string                `json:"episode_key"`
	OccurrenceKey       string                `json:"occurrence_key"`
	EvidenceFingerprint string                `json:"evidence_fingerprint"`
	Source              AlertSource           `json:"source"`
	Kind                AlertKind             `json:"kind"`
	PresentationCode    AlertPresentationCode `json:"presentation_code"`
	State               AlertEpisodeState     `json:"state"`
	Severity            AlertSeverity         `json:"severity"`
	EvidenceHealth      AlertEvidenceHealth   `json:"evidence_health"`
	Destination         AlertDestination      `json:"destination"`
	EvidenceAsOf        time.Time             `json:"evidence_as_of"`
	StateChangedAt      time.Time             `json:"state_changed_at"`
	ObservedAt          time.Time             `json:"observed_at"`
}

type AlertCandidateSnapshot struct {
	SchemaVersion  string                `json:"schema_version"`
	AuthorityScope string                `json:"authority_scope"`
	AsOf           time.Time             `json:"as_of"`
	CurrentState   AlertSnapshotState    `json:"current_state"`
	Coverage       AlertCoverage         `json:"coverage"`
	Sources        []AlertSourceCoverage `json:"sources"`
	Candidates     []AlertCandidate      `json:"candidates"`
}

type AlertCoverage struct {
	State           AlertCoverageState     `json:"state"`
	Freshness       AlertCoverageFreshness `json:"freshness"`
	AsOf            time.Time              `json:"as_of"`
	ExpectedSources []AlertSource          `json:"expected_sources"`
	CoveredSources  []AlertSource          `json:"covered_sources"`
}

type AlertCoverageFreshness string

type AlertCoverageState string

type AlertDestination string

type AlertEpisodeState string

type AlertEvidenceHealth string

type AlertKind string

type AlertPresentationCode string

type AlertSeverity string

type AlertSnapshotState string

type AlertSource string

type AlertSourceCoverage struct {
	Source         AlertSource         `json:"source"`
	Status         string              `json:"status"`
	Reason         string              `json:"reason"`
	EvidenceHealth AlertEvidenceHealth `json:"evidence_health"`
	InputAsOf      time.Time           `json:"input_as_of"`
	ObservedAt     time.Time           `json:"observed_at"`
	EvidenceAsOf   time.Time           `json:"evidence_as_of"`
	FreshUntil     time.Time           `json:"fresh_until"`
	Covered        bool                `json:"covered"`
}

type CapitalObservation struct {
	EquityBase float64
	AsOf       time.Time
}

type CapitalRuntime struct {
	// AdjustedPeakBase is the peak of (equity − cumulative external flows).
	AdjustedPeakBase float64
	PeakAsOf         time.Time
	// CumExternalFlowsBase is the policy-version-selected cumulative flow
	// input: declared events through v2, statement truth plus bridges in v3.
	CumExternalFlowsBase float64
	// Seeded is false until the first equity observation establishes the
	// peak; an unseeded state evaluates unknown, never ok.
	Seeded bool
	// BlockLatched persists across restarts and mark recovery; only a
	// journaled human reset clears it.
	BlockLatched bool
	// LastReconciledAt is the last human or automatic reconcile evidence;
	// zero means never reconciled.
	LastReconciledAt time.Time
	// UnreconciledOverrideUntil is populated only from an active, unexpired
	// one-shot override on capital.max_unreconciled_days. No other override
	// control reaches evaluation.
	UnreconciledOverrideUntil time.Time
}

type CapitalVerdict struct {
	Tier string
	// EffectiveRiskCapitalBase = min(declared, equity − floor); nil when
	// unapproved inputs or no usable equity observation.
	EffectiveRiskCapitalBase *float64
	// DrawdownBase and ConsumedPct measure from the cash-flow-adjusted
	// peak; ConsumedPct is drawdown / declared risk capital × 100.
	DrawdownBase *float64
	ConsumedPct  *float64
	EquityStale  bool
	// ReconcileStale means the declared-events ledger is older than
	// capital.max_unreconciled_days (or never attested).
	ReconcileStale bool
	Unapproved     []string
	Reasons        []string
}

type Constitution struct {
	Kind          string `toml:"kind" json:"kind"`
	SchemaVersion int    `toml:"schema_version" json:"schema_version"`
	PolicyID      string `toml:"policy_id" json:"policy_id"`
	PolicyVersion int    `toml:"policy_version" json:"policy_version"`

	Capital   ConstitutionCapital   `toml:"capital" json:"capital"`
	Drawdown  ConstitutionDrawdown  `toml:"drawdown" json:"drawdown"`
	Override  ConstitutionOverride  `toml:"override" json:"override"`
	Recon     ConstitutionRecon     `toml:"recon" json:"recon"`
	Cadence   ConstitutionCadence   `toml:"cadence" json:"cadence"`
	Inventory ConstitutionInventory `toml:"inventory" json:"inventory"`
}

type ConstitutionArtefact struct {
	Class string `toml:"class" json:"class,omitempty"`
}

type ConstitutionCadence struct {
	Morning ConstitutionArtefact `toml:"morning" json:"morning"`
	EOD     ConstitutionArtefact `toml:"eod" json:"eod"`
	Weekly  ConstitutionArtefact `toml:"weekly" json:"weekly"`
	// Nudges and Monthly are policy-version-4-only. Pointers preserve the
	// distinction between an absent table and an explicitly authored one, so
	// old policies can reject the new keys and v4 can report missing material.
	Nudges  *ConstitutionNudgeCadence   `toml:"nudges" json:"nudges,omitempty"`
	Monthly *ConstitutionMonthlyCadence `toml:"monthly" json:"monthly,omitempty"`
}

type ConstitutionCapital struct {
	BaseCurrency        string   `toml:"base_currency" json:"base_currency"`
	ProtectedFloor      *float64 `toml:"protected_floor" json:"protected_floor"`
	DeclaredRiskCapital *float64 `toml:"declared_risk_capital" json:"declared_risk_capital"`
	// MaxEquityAgeMinutes bounds trust in the last equity observation;
	// beyond it the evaluator marks the capital state stale and does not pass it.
	MaxEquityAgeMinutes *int `toml:"max_equity_age_minutes" json:"max_equity_age_minutes"`
	// MaxUnreconciledDays bounds trust in the declared capital-event ledger
	// between reconciliation evidence; expiry is reported as stale.
	MaxUnreconciledDays *int `toml:"max_unreconciled_days" json:"max_unreconciled_days"`
}

type ConstitutionDrawdown struct {
	WarnConsumedPct  *float64 `toml:"warn_consumed_pct" json:"warn_consumed_pct"`
	BlockConsumedPct *float64 `toml:"block_consumed_pct" json:"block_consumed_pct"`
	// BlockEnforcement is shadow (default when empty) or advisory in v1.
	BlockEnforcement string `toml:"block_enforcement" json:"block_enforcement"`
}

type ConstitutionInventory struct {
	Rulebook   *ConstitutionPolicyPin `toml:"rulebook" json:"rulebook,omitempty"`
	Protection *ConstitutionPolicyPin `toml:"protection" json:"protection,omitempty"`
	Stress     *ConstitutionPolicyPin `toml:"stress" json:"stress,omitempty"`
}

type ConstitutionLimit struct {
	Key         string `json:"key"`
	Value       string `json:"value"`
	Meaning     string `json:"meaning"`
	Source      string `json:"source"`      // file | default | unapproved
	Enforcement string `json:"enforcement"` // advisory | shadow | structural
}

type ConstitutionMonthlyCadence struct {
	Class        *string `toml:"class" json:"class"`
	DayOfMonth   *int    `toml:"day_of_month" json:"day_of_month"`
	NudgeAtLocal *string `toml:"nudge_at_local" json:"nudge_at_local"`
}

type ConstitutionNudgeCadence struct {
	Timezone             *string `toml:"timezone" json:"timezone"`
	ReconcileWarningDays *int    `toml:"reconcile_warning_days" json:"reconcile_warning_days"`
}

type ConstitutionOverride struct {
	MaxDurationHours *int `toml:"max_duration_hours" json:"max_duration_hours"`
}

type ConstitutionPolicyPin struct {
	ID      string `toml:"id" json:"id"`
	Version string `toml:"version" json:"version"`
}

type ConstitutionRecon struct {
	// A statement flow and a declared event match on amount when they
	// differ by at most max(amount_tolerance_pct% of the statement
	// amount, amount_tolerance_min in base currency).
	AmountTolerancePct *float64 `toml:"amount_tolerance_pct" json:"amount_tolerance_pct"`
	AmountToleranceMin *float64 `toml:"amount_tolerance_min" json:"amount_tolerance_min"`
	// DateWindowBusinessDays bounds how far apart the statement value
	// date and the declared effective date may sit (weekday count).
	DateWindowBusinessDays *int `toml:"date_window_business_days" json:"date_window_business_days"`
	// MaxReportAgeDays bounds how old the newest ingested statement may
	// be for a recon report to back a reconcile sign-off.
	MaxReportAgeDays *int `toml:"max_report_age_days" json:"max_report_age_days"`
	// MaxEquityDivergencePct bounds the absolute same-day difference between
	// broker statement equity and the runtime observation before v3 may
	// automatically accept a clean report as reconcile evidence.
	MaxEquityDivergencePct *float64 `toml:"max_equity_divergence_pct" json:"max_equity_divergence_pct"`
}

type EarningsInput struct {
	Known bool
	// NotApplicable marks fresh exact broker identity proving that this held
	// contract is a nonissuer security. It is independent from reviewed
	// terminal/non-reporting issuer evidence.
	NotApplicable bool
	// NonIssuerSecurity marks a holding whose security type has no issuer
	// earnings at all — an index, future, fund, or cash instrument. It rests on
	// the position's own security type rather than an exact broker proof, so it
	// is a weaker authority than NotApplicable and stays a separate field: a
	// reader must never mistake a typed classification for a proven contract.
	NonIssuerSecurity bool
	// TerminalNonReporting marks reviewed exact-contract evidence that no
	// future issuer earnings event applies. It is neither a known date nor an
	// unknown: rules 6-8 disclose an exemption for the relevant name.
	TerminalNonReporting bool
	Date                 time.Time // ET calendar date (midnight ET)
	TimeOfDay            string    // "amc" | "bmo" | "" (unspecified)
	Estimated            bool
	Stale                bool
	// SessionsUntil is the number of US equity sessions from today (ET) to
	// the earnings date inclusive, computed by the daemon via marketcal.
	// nil when unknown.
	SessionsUntil *int
	// Source is the daemon's closed provenance vocabulary. verified_terminal
	// means exact-contract authority was present; TerminalNonReporting is true
	// only when that authority is current, identity-matched, and conflict-free.
	Source string
	// Reason is a stable typed explanation for unknown/stale evidence. It is
	// disclosure only and never turns absence into a pass.
	Reason string
}

type Evaluation struct {
	Rows   []RuleRow
	Ranked []int
}

type LegInput struct {
	Desc       string // "NOW 20260717 C 130"
	Right      string // C | P
	Strike     float64
	Expiry     time.Time // ET calendar date
	DTE        int
	Quantity   float64 // signed contracts
	Multiplier float64
	Mark       float64
	Underlying *float64
	Delta      *float64
	// MarketValueBase is the signed base-currency mark value of the leg.
	MarketValueBase float64
	// MarketValueBaseSource discloses whether MarketValueBase was converted or
	// substituted: empty for a converted figure,
	// MarketValueBaseSourceSubstituted when no FX rate existed and the raw
	// contract-currency value stands in. Follows UnderlyingSource's shape.
	MarketValueBaseSource string
	// ExtrinsicBase is the base-currency extrinsic value for long legs;
	// nil when uncomputable (missing underlying or mark) — never zero it.
	ExtrinsicBase *float64
	// CostBasisBase is the base-currency premium paid for the leg (avg cost
	// is multiplier-inclusive on options — do not re-multiply); nil when the
	// gateway didn't deliver it.
	CostBasisBase *float64
	// FXToBase converts the leg's quote currency into base; nil when the FX
	// path is unknown (rule 1's lower bound then treats the leg as
	// unbounded).
	FXToBase *float64
	// UnderlyingSource discloses where Underlying came from: empty or
	// UnderlyingSourceGreeksTick for the per-leg model tick,
	// UnderlyingSourceStockLegMark for the same-name stock-leg join. Derived
	// spots support OTM-ness and extrinsic; they never classify hedge legs.
	UnderlyingSource string
	// HedgeListed marks the underlying as being on the policy hedge list.
	HedgeListed bool
}

type MonthlyPulseCompletion struct {
	Month             string
	PolicyFingerprint string
	// CompletedAt and Evidence are daemon-authored from paired brief render
	// evidence. Origin enforcement remains outside this pure evaluator.
	CompletedAt time.Time
	Evidence    string
}

type MonthlyPulseEvaluation struct {
	Status    string
	Month     string
	DueAt     time.Time
	Candidate *NudgeCandidate
}

type MonthlyPulseInput struct {
	Now               time.Time
	Cadence           ConstitutionCadence
	PolicyFingerprint string
	// PolicyEvidenceReady means current readable policy pins all match. Before
	// due it is ignored; from due onward false blocks both due and completion.
	PolicyEvidenceReady bool
	Completion          *MonthlyPulseCompletion
}

type NameInput struct {
	Symbol string
	// StockConID and StockSecType preserve the held underlying stock's broker
	// identity for exact-contract classifications. Zero means no stock leg or
	// no broker identity; symbol alone never activates such a classification.
	StockConID   int
	StockSecType string
	// UnderlyingSecType is the canonical security type of the held non-option
	// row for this name ("STOCK", "INDEX", "FUTURE", "FUND", ...). Unlike
	// StockSecType it is not narrowed to equities, because its job is to
	// recognize the types that have no issuer earnings. Empty for option-only
	// groups, which carry no such row and therefore no typed classification.
	UnderlyingSecType string
	// ExposureBase = stock + Σ delta×contracts×multiplier×spot, base ccy.
	ExposureBase float64
	// ExposureBaseComplete reports whether ExposureBase covers every leg the
	// aggregator saw (false when any priced leg was excluded: delta without
	// spot, markless stock, missing FX). Rule 1's lower bound refuses to
	// build on a partial sum — "proven ≥" must never overstate.
	ExposureBaseComplete bool
	// GreeksGapNotionalBase is |notional| of option legs missing delta —
	// exposure understatement risk.
	GreeksGapNotionalBase float64
	MarketValueBase       float64
	HasStockLeg           bool
	// StockDayChangePct is the stock leg's quote-enriched day change; nil
	// for option-only names or when enrichment failed.
	StockDayChangePct *float64
	Legs              []LegInput
}

type NudgeCandidate struct {
	Fingerprint string    `json:"fingerprint"`
	Kind        string    `json:"kind"`
	State       string    `json:"state"`
	Severity    string    `json:"severity"`
	Title       string    `json:"title"`
	Body        string    `json:"body"`
	OccurredAt  time.Time `json:"occurred_at,omitzero"`
	DueAt       time.Time `json:"due_at,omitzero"`
	ExpiresAt   time.Time `json:"expires_at,omitzero"`
	Destination string    `json:"destination"`
}

type NudgePinMismatch struct {
	Policy        string
	PinnedID      string
	PinnedVersion string
	LiveID        string
	LiveVersion   string
}

type PlannerMode string

type PlannerReadiness string

type Policy struct {
	Name    string `json:"name"`
	Profile string `json:"profile"`
	Version string `json:"version"`

	MarginUrgentPct float64 `json:"margin_urgent_pct"`
	MarginActPct    float64 `json:"margin_act_pct"`
	MarginWatchPct  float64 `json:"margin_watch_pct"`
	MarginTargetPct float64 `json:"margin_target_pct"`

	GrossExposureWatchPct float64 `json:"gross_exposure_watch_pct"`
	NetDeltaWatchPct      float64 `json:"net_delta_watch_pct"`
	GrossDeltaWatchPct    float64 `json:"gross_delta_watch_pct"`

	GrossExposureStressActPct float64 `json:"gross_exposure_stress_act_pct"`
	NetDeltaStressActPct      float64 `json:"net_delta_stress_act_pct"`
	GrossDeltaStressActPct    float64 `json:"gross_delta_stress_act_pct"`

	GrossExposureStressUrgentPct float64 `json:"gross_exposure_stress_urgent_pct"`
	NetDeltaStressUrgentPct      float64 `json:"net_delta_stress_urgent_pct"`
	GrossDeltaStressUrgentPct    float64 `json:"gross_delta_stress_urgent_pct"`

	SingleNameExposureWatchPct float64 `json:"single_name_exposure_watch_pct"`
	SingleNameDeltaWatchPct    float64 `json:"single_name_delta_watch_pct"`
	SingleNameTargetPct        float64 `json:"single_name_target_pct"`

	OptionGreeksMinCoveragePct float64 `json:"option_greeks_min_coverage_pct"`

	SPYDropPct      float64 `json:"spy_drop_pct"`
	SPYHardDropPct  float64 `json:"spy_hard_drop_pct"`
	SPYCrashPct     float64 `json:"spy_crash_pct"`
	SPYRallyPct     float64 `json:"spy_rally_pct"`
	SPYHardRallyPct float64 `json:"spy_hard_rally_pct"`

	VIXSpikePct     float64 `json:"vix_spike_pct"`
	VIXHardSpikePct float64 `json:"vix_hard_spike_pct"`
	VIXCrushPct     float64 `json:"vix_crush_pct"`
	VIXHardCrushPct float64 `json:"vix_hard_crush_pct"`

	DailyPnLWatchPct float64 `json:"daily_pnl_watch_pct"`
	DailyPnLActPct   float64 `json:"daily_pnl_act_pct"`

	HeldStressMaterialPct             float64 `json:"held_stress_material_pct"`
	HeldUnderlyingPnLWatchPct         float64 `json:"held_underlying_pnl_watch_pct"`
	HeldUnderlyingPnLActPct           float64 `json:"held_underlying_pnl_act_pct"`
	HeldOptionNearDTE                 int     `json:"held_option_near_dte"`
	HeldOptionDeltaWatchPct           float64 `json:"held_option_delta_watch_pct"`
	HeldOptionDeltaActPct             float64 `json:"held_option_delta_act_pct"`
	HeldLiquidityStockSpreadPct       float64 `json:"held_liquidity_stock_spread_pct"`
	HeldLiquidityOptionSpreadPctOfMid float64 `json:"held_liquidity_option_spread_pct_of_mid"`

	Reduce ReducePolicy `json:"reduce"`
}

type PortfolioPosture string

type ReconcileDueInput struct {
	Now         time.Time
	Deadline    time.Time
	WarningDays *int
}

type ReconcileExceptionIdentity struct {
	Kind     string
	Identity string
	Material []string
}

type ReducePolicy struct {
	FrontDTE                int     `json:"front_dte"`
	MidDTE                  int     `json:"mid_dte"`
	HedgeOffsetMinPct       float64 `json:"hedge_offset_min_pct"`
	HedgeOffsetMaxPct       float64 `json:"hedge_offset_max_pct"`
	MaxOptionSpreadAbs      float64 `json:"max_option_spread_abs"`
	MaxOptionSpreadPctOfMid float64 `json:"max_option_spread_pct_of_mid"`
	OrderType               string  `json:"order_type"`
	TIF                     string  `json:"tif"`
	AllowMarketOrders       bool    `json:"allow_market_orders"`
}

type RegimeThresholds struct {
	CashSellOnlyPct   float64 `toml:"cash_sell_only_pct" json:"cash_sell_only_pct"`
	ExtrinsicWatchPct float64 `toml:"extrinsic_watch_pct" json:"extrinsic_watch_pct"`
	ExtrinsicActPct   float64 `toml:"extrinsic_act_pct" json:"extrinsic_act_pct"`
	HedgeBandMinPct   float64 `toml:"hedge_band_min_pct" json:"hedge_band_min_pct"`
	HedgeBandMaxPct   float64 `toml:"hedge_band_max_pct" json:"hedge_band_max_pct"`
}

type RuleInputs struct {
	AsOf         time.Time
	BaseCurrency string

	Positions SourceState
	Account   SourceState

	NLVBase      *float64
	CashBase     *float64
	DailyPnLBase *float64

	Names []NameInput

	// SessionOpen: US equity regular session per marketcal.
	SessionOpen bool
	// SPYDayChangePct is the market tape for rule 9; nil when unavailable.
	SPYDayChangePct *float64

	Earnings map[string]EarningsInput

	// RegimeStage is the bucketed regime lifecycle stage (RegimeBucket*);
	// empty when no stage has ever been observed. RegimeStageCarried marks a
	// stage older than the policy max age or restored from the persisted
	// store — carried stages evaluate worse-of(carried set, calm set).
	RegimeStage        string
	RegimeStageAsOf    time.Time
	RegimeStageCarried bool

	// NonBaseNLVBase is the base-currency net liquidation held in non-base
	// currencies (rule 14). nil = unavailable (absent currency report,
	// missing FX) — never zero it: an empty currency report on a book with
	// non-base legs is a data gap, not a base-only book.
	NonBaseNLVBase *float64
	// NonBaseCurrencies names the currencies behind NonBaseNLVBase.
	NonBaseCurrencies []string
}

type RuleOffender struct {
	Symbol     string  `json:"symbol"`
	Leg        string  `json:"leg,omitempty"`
	Observed   float64 `json:"observed"`
	ImpactBase float64 `json:"impact_base,omitempty"`
	Note       string  `json:"note,omitempty"`
}

type RuleRow struct {
	ID         string         `json:"id"`
	Number     int            `json:"number"`
	Title      string         `json:"title"`
	Status     string         `json:"status"`
	Observed   *float64       `json:"observed,omitempty"`
	Threshold  *float64       `json:"threshold,omitempty"`
	Unit       string         `json:"unit,omitempty"`
	Evidence   string         `json:"evidence"`
	Reason     string         `json:"reason,omitempty"`
	Offenders  []RuleOffender `json:"offenders,omitempty"`
	Exempt     []RuleOffender `json:"exempt,omitempty"`
	ImpactBase float64        `json:"impact_base,omitempty"`
	Notes      []string       `json:"notes,omitempty"`
	// ObservedIsLowerBound marks Observed as a provable minimum computed
	// from partial inputs ("≥ X%"), not an exact measurement. Only breaches
	// may carry it — a lower bound can indict, never acquit.
	ObservedIsLowerBound bool `json:"observed_is_lower_bound,omitempty"`
}

type RulebookPolicy struct {
	ID      string `toml:"id" json:"id"`
	Version int    `toml:"version" json:"version"`

	// Rule 1 — single_name_exposure (% of NLV, delta-dollar exposure).
	SingleNameWatchPct float64 `toml:"single_name_watch_pct" json:"single_name_watch_pct"`
	SingleNameActPct   float64 `toml:"single_name_act_pct" json:"single_name_act_pct"`

	// Rule 2 — option_line_premium (% of NLV, long option line market value).
	// Hedge-classified legs (rule12HedgeLeg) evaluate against the hedge tier;
	// rule 12 owns hedge sizing, this tier only bounds premium at risk.
	OptionLineWatchPct float64 `toml:"option_line_watch_pct" json:"option_line_watch_pct"`
	OptionLineActPct   float64 `toml:"option_line_act_pct" json:"option_line_act_pct"`
	HedgeLineWatchPct  float64 `toml:"hedge_line_watch_pct" json:"hedge_line_watch_pct"`
	HedgeLineActPct    float64 `toml:"hedge_line_act_pct" json:"hedge_line_act_pct"`

	// Rule 5 — expiry_runway (calendar DTE bounds for long options).
	RunwayWatchDTE      int     `toml:"runway_watch_dte" json:"runway_watch_dte"`
	RunwayActDTE        int     `toml:"runway_act_dte" json:"runway_act_dte"`
	RunwayITMDeltaFloor float64 `toml:"runway_itm_delta_floor" json:"runway_itm_delta_floor"`

	// Rule 7 — overwrite_earnings short-put act tier: a spanning short put
	// escalates from watch to act when its assignment notional reaches the
	// line share of NLV, or a name's spanning short puts together reach the
	// name share.
	ShortPutActLinePctNLV float64 `toml:"short_put_act_line_pct_nlv" json:"short_put_act_line_pct_nlv"`
	ShortPutActNamePctNLV float64 `toml:"short_put_act_name_pct_nlv" json:"short_put_act_name_pct_nlv"`

	// Rule 8 — earnings_size_freeze (US sessions to earnings).
	EarningsFreezeSessions int `toml:"earnings_freeze_sessions" json:"earnings_freeze_sessions"`

	// Rules 9/10 — tape thresholds (day-change %).
	RedOnGreenNameDropPct float64 `toml:"red_on_green_name_drop_pct" json:"red_on_green_name_drop_pct"`
	RedOnGreenSPYUpPct    float64 `toml:"red_on_green_spy_up_pct" json:"red_on_green_spy_up_pct"`
	WinnerTrimDayUpPct    float64 `toml:"winner_trim_day_up_pct" json:"winner_trim_day_up_pct"`
	WinnerTrimMinExpoPct  float64 `toml:"winner_trim_min_exposure_pct" json:"winner_trim_min_exposure_pct"`

	// Rules 3/4/12 — regime-conditional threshold sets. A fresh regime stage
	// selects its set; a carried or never-seen stage evaluates the carried set
	// AND the calm set
	// and keeps the worse verdict, so stale regime data can hold or tighten
	// a verdict but never relax it.
	RegimeCalm         RegimeThresholds `toml:"regime_calm" json:"regime_calm"`
	RegimeEarlyWarning RegimeThresholds `toml:"regime_early_warning" json:"regime_early_warning"`
	RegimeConfirmed    RegimeThresholds `toml:"regime_confirmed" json:"regime_confirmed"`
	// RegimeStageMaxAgeMinutes bounds trust in the latched regime stage;
	// older stages evaluate as carried (worse-of semantics above).
	RegimeStageMaxAgeMinutes int `toml:"regime_stage_max_age_minutes" json:"regime_stage_max_age_minutes"`

	// Rule 13 — exit_discipline (% of premium paid lost on a long line).
	ExitWatchLossPct float64 `toml:"exit_watch_loss_pct" json:"exit_watch_loss_pct"`
	ExitActLossPct   float64 `toml:"exit_act_loss_pct" json:"exit_act_loss_pct"`

	// Rule 14 — fx_exposure (% of NLV held in non-base currencies). This is a
	// watch-only structural condition.
	FXExposureWatchPct float64 `toml:"fx_exposure_watch_pct" json:"fx_exposure_watch_pct"`

	// HedgeSymbols is the policy-owned index list whose long puts classify
	// as hedges (rules 1, 2, 5, 12, 13). Uppercased on load.
	HedgeSymbols []string `toml:"hedge_symbols" json:"hedge_symbols"`

	// GreeksGapFloorPctNLV is the materiality floor: a name whose legs
	// missing delta exceed this notional share of NLV renders its
	// exposure-dependent rows unknown instead of silently understating.
	GreeksGapFloorPctNLV float64 `toml:"greeks_gap_floor_pct_nlv" json:"greeks_gap_floor_pct_nlv"`

	// EarningsStaleDays bounds trust in a fetched earnings date; older
	// observations flip rules 6-8 to unknown until refreshed or overridden.
	EarningsStaleDays int `toml:"earnings_stale_days" json:"earnings_stale_days"`
}

type ShadowWouldBlockEvaluation struct {
	Candidate *NudgeCandidate
	Count     int
}

type ShadowWouldBlockInput struct {
	PolicyFingerprint string
	LatchEpisode      string
	RiskIncreasing    bool
	Exempt            bool
	WouldBlock        bool
	PriorCount        int
	OccurredAt        time.Time
}

type Signal struct {
	ID               SignalID         `json:"id"`
	Direction        SignalDirection  `json:"direction"`
	Posture          PortfolioPosture `json:"posture,omitempty"`
	Severity         SignalSeverity   `json:"severity"`
	Subject          string           `json:"subject,omitempty"`
	Metric           string           `json:"metric,omitempty"`
	Observed         *float64         `json:"observed,omitempty"`
	Threshold        *float64         `json:"threshold,omitempty"`
	Target           *float64         `json:"target,omitempty"`
	Unit             string           `json:"unit,omitempty"`
	Evidence         string           `json:"evidence,omitempty"`
	Confidence       string           `json:"confidence,omitempty"`
	ConfidenceImpact string           `json:"confidence_impact,omitempty"`
	BlockedBy        []string         `json:"blocked_by,omitempty"`
}

type SignalDirection string

type SignalID string

type SignalSeverity string

type SizeInput struct {
	Symbol      string
	Side        string  // "long" | "short"
	Entry       float64 // quote currency
	Stop        float64 // quote currency
	Target      float64 // optional take-profit; 0 disables the R block
	RiskPct     float64 // percent of NLV; (0, 100]
	Lot         int     // round shares down to this multiple; >= 1
	FX          float64 // quote-currency units per 1 base-currency unit; > 0
	NLV         float64 // base currency
	BuyingPower float64 // base currency (0 disables BP check)
	Currency    string  // base currency code, surfaced in output only
}

type SizeResult struct {
	Symbol           string   `json:"symbol"`
	Side             string   `json:"side"`
	Entry            float64  `json:"entry"`
	Stop             float64  `json:"stop"`
	Target           *float64 `json:"target,omitempty"`
	RiskPct          float64  `json:"risk_pct"`
	Lot              int      `json:"lot"`
	FX               float64  `json:"fx"`
	NLV              float64  `json:"nlv"`
	BaseCurrency     string   `json:"base_currency,omitempty"`
	RiskBase         float64  `json:"risk_base"`  // NLV * pct/100
	RiskQuote        float64  `json:"risk_quote"` // RiskBase * fx
	PerShareRisk     float64  `json:"per_share_risk"`
	Shares           int      `json:"shares"`
	Notional         float64  `json:"notional"`    // shares * entry
	MaxLoss          float64  `json:"max_loss"`    // shares * per_share_risk (quote ccy)
	R                *float64 `json:"r,omitempty"` // (|target-entry|) / (|entry-stop|)
	RewardQuote      *float64 `json:"reward_quote,omitempty"`
	RewardBase       *float64 `json:"reward_base,omitempty"`
	BreakevenWinRate *float64 `json:"breakeven_win_rate,omitempty"` // 1 / (1+R), fraction
	Status           string   `json:"status"`                       // "ok" | "tight_risk" | "exceeds_buying_power"
}

type SourceState struct {
	Healthy bool
	Reason  string // positions_pending, account_unavailable, …
}

type UnreconciledClock struct {
	Approved      bool
	Deadline      time.Time
	DaysRemaining *int
	Stale         bool
}