intent

type Config struct {
	// Enabled turns the check on. Default false. When false, the hook
	// short-circuits — no embedder calls, no audit emit.
	Enabled bool

	// Threshold is the SOFT similarity floor. Scores strictly below
	// threshold but at-or-above HardThreshold produce DecisionWarn.
	// Sensible default 0.5 — operators SHOULD start warn-only for a
	// sprint to gather the score distribution before turning deny on.
	Threshold float64

	// HardThreshold is the HARD floor. Scores strictly below produce
	// DecisionDeny. Set equal to Threshold to disable the warn tier;
	// set to a negative value (e.g. -1) to run warn-only during the
	// initial rollout. Sensible default 0.3.
	HardThreshold float64

	// CacheSize is the max number of action-side embeddings to
	// remember in the LRU. Zero disables the action cache (still
	// caches the per-task intent). 1024 is a reasonable default.
	CacheSize int

	// IntentTTL controls how long a task's intent embedding is
	// kept in memory before it's evicted. Zero → 1 hour default.
	IntentTTL time.Duration
}

type Decision int

type DriftConfig struct {
	// Enabled turns the analyzer on. When false, RecordAndCheck is
	// a no-op and no drift signals fire.
	Enabled bool

	// Window is the number of most-recent scores considered by the
	// rolling-mean test. Must be ≥ 2 — a window of 1 can't
	// distinguish "trending down" from "just low."
	Window int

	// DriftThreshold is the mean-score floor. When the rolling
	// window mean falls strictly below this value, drift enters
	// the "mean_below_threshold" state.
	DriftThreshold float64

	// MonotoneN, when non-zero, additionally trips drift when the
	// last N scores are strictly decreasing (even if the mean is
	// still above DriftThreshold). Catches slow-boil patterns
	// where each individual step is small but cumulative drift is
	// large. Zero disables the monotone check.
	MonotoneN int
}

type DriftSignal struct {
	// Severity is the human-readable classification. One of
	// "mean_below_threshold", "monotone_decrease", "both", or
	// "recovered" (transition OUT of drift).
	Severity string

	// Mean is the rolling-window mean of the last Window scores at
	// the moment the signal fired. Included on both entry and
	// recovery transitions for the audit event.
	Mean float64

	// Window is the number of scores in the mean.
	Window int

	// Transition is "entered" for on-entry signals or "recovered"
	// for the exit signal. Makes SIEM queries "when did I go into
	// drift?" trivial.
	Transition string
}

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

type Result struct {
	// Score is the cosine similarity ∈ [-1, 1]. NaN when the engine
	// couldn't produce a value (embedder error, missing intent).
	Score float64

	// Decision is the alignment engine's verdict.
	Decision Decision

	// Reason is a short human-readable classification — surfaced on
	// the audit event and, on Deny, returned as the tool-exec error.
	Reason string

	// Drift is non-nil ONLY on the tool call that transitions the
	// task into or out of drift (R7 / #214). The hook consumer
	// emits an `intent_drift` audit event when set. State-transition
	// semantics keep the audit stream from flooding across long
	// stretches of drift.
	Drift *DriftSignal
}